Building docs on GitHub

To host on GitHub Pages, you configuring the settings in the project (Settings -> Pages -> Source branch) to a branch. Thereafter, any content in that branch is automatically hosted at https://<user>.github.io/<project>.

A common pattern is to maintain a separate branch called gh-pages, and keep it completely cleaned out except for the built HTML documentation (with index.html as the top level).

This template documentation uses GitHub Actions to build the docs and push to gh-pages. If you’re going to be using the GitHub Actions config, you’ll need to create that branch manually first:

# Assuming there's nothing in your repo yet.
git checkout -b gh-pages

# If you have anything commited, use `git rm *` to completely
# clean out this branch.

# Then assuming your remote is on GitHub
git push origin gh-pages

# Get back to the main branch
git checkout main

This repo uses GitHub Actions to set up an environment, build the docs, and add to the gh-pages branch, which is automatically served at the URL https://<user>.github.io/<project>, which in this case is https://nichd-bspc.github.io/documentation-template.

The configuration is in .github/workflows/main.yml. It’s generic, so as long as you use gh-pages and have the source directory separate from build, it should work.

This GitHub Actions configuration will:

• install conda and any dependencies in requirements.txt

• run doctests

• build the docs

• commit them to the gh-pages branch

• upload them as an artifact in the Actions web interface so you can inspect

From the Actions tab of the GitHub interface, you can click on a job and look for the Artifacts section to download the built docs. This can be nice for contributors to see the results of their changes without needing to set everything up locally.

It will do those steps on every push. If we’re on the main branch, then the docs will also be pushed to the gh-pages branch, at which time they will be publicly available at https://<user>.github.io/<project>.

Note

Note that GitHub by default expects pages generated by Jekyll. You need to add a file at the top level of your repo, .nojekyll, to tell GitHub to not expect Jekyll-generated docs. The GitHub Actions for this repo take care of this.

.github/workflows/main.yml

You can find the configuration in this repository under .github/workflows/main.yml, and it is included directly in this documentation here:

# This GitHub Actions configuration will install conda, run doctests, build the
# docs, commit them to the gh-pages branch, upload them as an artifact so you
# can inspect. It will do this on every push. If we're on the `main` branch,
# then the docs will be pushed to the gh-pages branch, at which time they will
# be publicly available at https://<user>.github.io/<project>.
#
# Note: there are actions that can be used to wrap up some of this
# configuration. But I find it more useful to do thing the "long way" because
# it's easier to customize later when needed.


# This name will show up in the Actions interface.
name: main

# Run everything here on every push to the repo.
on: [push]

jobs:

  build-and-test:

    # This is the base image we'll be using. It's Ubuntu plus conveniently
    # installed extras like conda.
    runs-on: "ubuntu-latest"
    steps:

    # All our steps will need the code, so we use this action to check out our
    # repo for us
    - uses: actions/checkout@v2

    # Set up conda environment for subsequent jobs. If you need other packages,
    # add them to requirements.txt
    - name: build env
      run: |  # Note the "|" which indicates "a multiline string follows"

        # The base GitHub Ubuntu image has conda already installed.
        # The eval call does the equivalent of "conda init bash" and we will
        # use it at the beginning of subsequent steps that need to use conda.
        eval "$(conda shell.bash hook)"
        conda create -p ./env --file requirements.txt --channel conda-forge

    # Run doctests (delete this if you are not using doctests)
    - name: run doctests
      run: |
        eval "$(conda shell.bash hook)"
        conda activate ./env
        (cd doc && make doctest)

    # Build docs here, and copy them over to a temp directory that is a clone
    # of the gh-pages branch.
    - name: build docs
      run: |
        # Activate env and build docs
        eval "$(conda shell.bash hook)"
        conda activate ./env
        (cd doc && make html)

        # Clone just the gh-pages branch to a temp dir.
        git clone \
          --single-branch \
          --branch gh-pages "https://x-access-token:${{ secrets.GITHUB_TOKEN }}@github.com/$GITHUB_REPOSITORY" \
          /tmp/doc

        # Clean out that temp dir because we're about to move our just-built
        # docs there
        rm -rf /tmp/doc/*
        cp -r doc/build/html/* /tmp/doc

        # GitHub defaults to assuming Jekyll pages; the presence of this file
        # makes Sphinx pages work properly with GitHub
        touch /tmp/doc/.nojekyll

    # Upload the built docs as an artifact for inspection (even on PRs). This
    # will show up in the Actions web interface.
    - name: push artifact
      uses: actions/upload-artifact@v2
      with:
        name: doc
        path: /tmp/doc

    # Push docs to gh-pages but ONLY if this test is running on master branch
    - name: push docs to gh-pages branch
      if: ${{ (github.ref == 'refs/heads/main') }}
      run: |

        # Commit our changes to the gh-pages branch
        cd /tmp/doc
        git config --global user.email "action@github.com"
        git config --global user.name "GitHub Action"
        git add .

        # git commit exits nonzero if nothing to commit, but we don't want to
        # consider that an error so we ignore it.
        git commit -m 'update docs' -a || true

        # Push the gh-pages branch. Once this happens, your changes will be
        # live (though could take a couple mins to show up)
        git push "https://x-access-token:${{ secrets.GITHUB_TOKEN }}@github.com/$GITHUB_REPOSITORY" gh-pages