Introduction
In this lesson we will build a github.io site for the upcoming training of the DUNE Computing HWDB which has learning materials presented using the Software Carpentry (SC) templates.
Identify SC lesson template source: Work from the latest version of the lesson template, to verify versioning, visit https://github.com/swcarpentry, and check out the meta-repository to help navigate the lessons and repos of the SC Community: https://github.com/swcarpentry/swcarpentry.
Build Note
Observing file dates at https://github.com/carpentries/styles indicates no commits to the styles repo have been made in the last 2 years, with latest release: styles v9.5.3 Latest on Aug 21, 2018. All styles development work has shifted to their Workbench project, still in a beta stage.
Steps in a Nutshell
- Copy styles .git URL to buffer
- Create DUNE GitHub instance
- Import styles (not fork, not clone)
- GitHub settings, set default branch to gh-pages, then delete the main branch.
- Locally, clone your github instance using GitHub Desktop
- In a terminal window whle in top level of your repo, and using $python bin/lesson_initialize.py
- Run $make serve to enable Jekyll/Ruby/Bundler based editing for localhost viewing
- Make edits, when ready push updates to the master repo on Github
User Setup Expectations
- Versed at building GitHub repo.
- Capable of using GitHub Desktop.
- Has an editing environment such as emacs configured on their development computer.
- Has installed Ruby/Jekyll development framework for localhost editing.
- Markdown as a program language is understood.
Step by Step Instructions
>> Assumes user has familiarity with Github, and we encourage the Jekyll/Ruby development environment is used locally to verify content before pushing to Github.
We will build from the styles lesson by importing it into a new DUNE GitHub repo using the source given at: swcarpentry/styles. Have a look at https://github.com/carpentries/styles.
Select the green <> Code button, and grab (copy URL to clipboard) the URL for the Clone (https://github.com/carpentries/styles.git)
Now go to: https://github.com/DUNE/
Select Repositories tab from the menu, use New repository (green button)
Instead of creating a new repository, follow the Import a repository link which is located in the opening paragraph.
The link to Import a repository → https://github.com/new/import
Enter your old repository’s clone URL as https://github.com/carpentries/styles.git, declare Your new repository details as: DUNE/computing-HWDB, and as Public, then select the green Begin import button.
Why Import, and not Clone?
Clone vs. Fork vs. Import - Repo owner approves all changes through pull requests. Fork - creates a local and remote copy of a repo. You become the owner of the forked repo, but it remains linked to the original repo. Import - creates a local and remote copy of a repo that is unlinked from the original.
Reference: https://joshuadull.github.io/GitHub-Desktop/03-sharing/index.html
Go to the new repo is https://github.com/DUNE/computing-HWDB to verify the installation.
Notice the default branch is main, showing minimal content, except, “Please use the gh-pages branch. Inspect the contents of the gh-pages branch by selecting the main branch dropdown and selecting gh-pages.
We will change the default branch to gh-pages and delete the main branch. Set the default branch of the repo to gh-pages by going to the Settings tab (top menu next the gear icon) or directly: https://github.com/DUNE/computing-HWDB/settings where in the Default branch block:
Select the left-right arrow button and the gh-pages branch, then the Update button
Then accept the responsibility of change to gh-pages
Afterwards, select the <>Code tab (top menu bar)
And then the “2 Branches” tab (right of gh-pages) delete the main branch by following the Branches icon in the left menu
And use the trash can to delete the main branch, the results:
Returning <> Code, we now have a base instance of the styles lesson template parked as a DUNE repo.
Our goal is to build the .io site from our local editing environment using GitHub Desktop to manage the edits which include a couple critical actions, the first being creating the _config.yml file.
Using GitHub Desktop on your Mac or PC, Clone the Repository… https://github.com/DUNE/computing-HWDB.git
Selecting DUNE/computing-HWDB which is filtered from those available at GitHub.com assuming your GitHub/DUNE credentials are correct.
Verify your new repo has been stashed as a Local Path, and select the CLone (blue) button.
Inspect the file list for your repository in a Terminal window.
Create necessary initial files $ python bin/lesson_initialize.py
And reinspect
Notice several files have been generated (13), _config.yml, index.md, README.md being among those that require configuration edits.
Verify the installation by running $make serve and inspecting the local version of the .io website via your web browser the URL http://127.0.1:4000
Notice the Changes to the repo on your GitHub Desktop app, then provide a Summary, and a short Description, then Commit to gh-pages (blue button) to load the new files, following up with a Push to Origin (https://github.com/DUNE/computing-HWDB).
With these files in place, https://dune.github.io/computing-HWDB/ will be generated automatically. See Settings:Pages to verify the site is live:
Now we are ready to build out the site for public use.
Back at github.com/DUNE/computing-HWDB add an about:
The dune.github.io/computing-HWDB site is now ready for customization that includes index.md, README.md, setup.md. Morevoer, the episodes can be constructed when a schedule will be automatically generated for display.
A good time to take a break!