SwissPedHealth PipeDev Docs

This is the initial README for the PipelineDev documentation pages: https://swisspedhealth-pipelinedev.github.io/docs/.

Cloning and keys

Summary

Instead of the default method for cloning, I specify my username for github to clone: git clone git@dylanlawless.github.com:SwissPedHealth-PipelineDev/docs.git

Then set the local user cd docs git config user.email personemail@addess.com git config user.name DylanLawless

Datails of why this is done

Since I work with others and use different accounts, machines, emails, here are some notes incase you or I need them.

To push to multiple github accounts with different keys, and different machines, these settings can be used. Instead of a global git config, local configs are used for each repo. Here is the example with two of my repos. The custom usernames for the local repo is shown (but custom email is removed to prevent spam). Create your ssh keys as per github recommendation. In the .ssh directory, the config file will assign the key to each git repository that you clone based on the Host that you use. i.e. custom instead of the default:

• git clone git@custom.github.com:accout/repo.git
• git clone git@github.com:accout/repo.git

## Set up the ssh config file
cd ~/.ssh/config

## set such that Host and User are custom
# lawlessgenomics repo
Host dylanlawless.github.com
  HostName github.com
  User DylanLawless
  PreferredAuthentications publickey
  IdentityFile ~/.ssh/key1_rsa
  IdentitiesOnly yes

# sarscov2 repo
Host sarscov2voc.github.com
  HostName github.com
  User sars-cov-2-voc
  PreferredAuthentications publickey
  IdentityFile ~/.ssh/key2_rsa
  IdentitiesOnly yes

Then clone your repo using the custom Host instead of the default provided by github when you use button "clone/ssh/copy".

# Clone using the correct Host as per config.
# As shown at the end of this page, you may need to clone with submodules.
# You can do by add the "--recursive" flag. 
git clone --recursive git@dylanlawless.github.com:SwissPedHealth-PipelineDev/docs.git

# Set the local user here (instead of global, i.e. /Users/user/.gitconfig)
cd "the cloned repo dir"
git config user.email personemail@addess.com
git config user.name DylanLawless

# Clone using the correct Host as per config
git clone git@sarscov2voc.github.com:sars-cov-2-voc/SARS-CoV-2-VOC.github.io.git

cd "the clone repo dir"
git config user.email someotheremail@address.com
git config user.name sars-cov-2-voc

You should now be able to pull and push from that repo without the "incorrect user" problems.

Just the Docs theme

We use the bare-minimum template to create a Jekyll site that:

• uses the Just the Docs theme;
• can be built and published on GitHub Pages;
• can be built and previewed locally, and published on other platforms.

More specifically, the created site:

• uses a gem-based approach, i.e. uses a Gemfile and loads the just-the-docs gem;
• uses the GitHub Pages / Actions workflow to build and publish the site on GitHub Pages.

To get started with creating a site, just click "use this template"!

If you want to maintain your docs in the docs directory of an existing project repo, see Hosting your docs from an existing project repo.

After completing the creation of your new site on GitHub, update it as needed:

Replace the content of the template pages

Update the following files to your own content:

• index.md (your new home page)
• README.md (information for those who access your site repo on GitHub)

Changing the version of the theme and/or Jekyll

Simply edit the relevant line(s) in the Gemfile.

Adding a plugin

The Just the Docs theme automatically includes the jekyll-seo-tag plugin.

To add an extra plugin, you need to add it in the Gemfile and in _config.yml. For example, to add jekyll-default-layout:

• Add the following to your site's Gemfile:

  gem "jekyll-default-layout"

• And add the following to your site's _config.yml:

  plugins:
    - jekyll-default-layout

Note: If you are using a Jekyll version less than 3.5.0, use the gems key instead of plugins.

Publishing your site on GitHub Pages

1. If your created site is YOUR-USERNAME/YOUR-SITE-NAME, update _config.yml to:

   title: YOUR TITLE
   description: YOUR DESCRIPTION
   theme: just-the-docs
   
   url: https://YOUR-USERNAME.github.io/YOUR-SITE-NAME
   
   aux_links: # remove if you don't want this link to appear on your pages
     Template Repository: https://github.com/YOUR-USERNAME/YOUR-SITE-NAME

2. Push your updated _config.yml to your site on GitHub.

3. In your newly created repo on GitHub:

   • go to the Settings tab -> Pages -> Build and deployment, then select Source: GitHub Actions.
   • if there were any failed Actions, go to the Actions tab and click on Re-run jobs.

Building and previewing your site locally

Assuming Jekyll and Bundler are installed on your computer:

1. Change your working directory to the root directory of your site.

2. Run bundle install.

3. Run bundle exec jekyll serve to build your site and preview it at localhost:4000.

   The built site is stored in the directory _site.

Publishing your built site on a different platform

Just upload all the files in the directory _site.

Customization

You're free to customize sites that you create with this template, however you like!

Browse our documentation to learn more about how to use this theme.

Hosting your docs from an existing project repo

You might want to maintain your docs in an existing project repo. Instead of creating a new repo using the just-the-docs template, you can copy the template files into your existing repo and configure the template's Github Actions workflow to build from a docs directory. You can clone the template to your local machine or download the .zip file to access the files.

Copy the template files

1. Create a .github/workflows directory at your project root if your repo doesn't already have one. Copy the pages.yml file into this directory. Github Actions searches this directory for workflow files.

2. Create a docs directory at your project root and copy all remaining template files into this directory.

Modify the Github Actions worklow

The Github Actions workflow that builds and deploys your site to Github Pages is defined by the pages.yml file. You'll need to edit this file to that so that your build and deploy steps look to your docs directory, rather than the project root.

1. Set the default working-directory param for the build job.

   build:
     runs-on: ubuntu-latest
     defaults:
       run:
         working-directory: docs

2. Set the working-directory param for the Setup Ruby step.

   - name: Setup Ruby
       uses: ruby/setup-ruby@v1
       with:
         ruby-version: '3.1'
         bundler-cache: true
         cache-version: 0
         working-directory: '${{ github.workspace }}/docs'

3. Set the path param for the Upload artifact step:

   - name: Upload artifact
       uses: actions/upload-pages-artifact@v1
       with:
         path: "docs/_site/"

4. Modify the trigger so that only changes within the docs directory start the workflow. Otherwise, every change to your project (even those that don't affect the docs) would trigger a new site build and deploy.

   on:
     push:
       branches:
         - "main"
       paths:
         - "docs/**"

Licensing and Attribution

This repository is licensed under the MIT License. You are generally free to reuse or extend upon this code as you see fit; just include the original copy of the license (which is preserved when you "make a template"). While it's not necessary, we'd love to hear from you if you do use this template, and how we can improve it for future use!

The deployment GitHub Actions workflow is heavily based on GitHub's mixed-party starter workflows. A copy of their MIT License is available in actions/starter-workflows.

---