Hosting Sphinx on GitHub Pages

While you can install Sphinx on your laptop and build documentation locally, ultimately you will want to share docs via a web server. To do this, we will go over:

1. Setting up GitHub pages for a repository

2. Using GitHub Workflows to automate building documentation

1. Set up GitHub Pages

GitHub Pages allow users to view web pages generated by our documentation. While there already a page set up for the sphinx-documentation-demo project, you will need to do the following steps for a new project:

1a. Navigate to Page settings

Click the Settings tab in the project you want to add to GitHub Pages.

Click the Pages tab (in the left sidebar) in the Settings page.

1b. Select branch to use with GitHub Pages

Warning

The GitHub repo must be public in order for it to be accessible via GitHub Pages.

When documentation is successfully deployed, you will see a link that looks like A. For a new repo, this will not be active. You will need to set the branch (see B). This demo uses a separate branch called gh-pages to deploy documentation.

2. Using GitHub Workflow to Build Documentation

GitHub can automatically discover workflows located in the .github/workflows directory within the project directory. We will be using a workflow to build documentation whenever a new commit is pushed to the repository.

2a. Example Workflow

We will be reviewing the workflow that sphinx-documentation-demo uses.

You can find the workflow in sphinx-documentation-demo/.github/workflows/documentation.yml

name: documentation

on: [push, pull_request, workflow_dispatch]

permissions:
contents: write

jobs:
docs:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v3
    - uses: actions/setup-python@v3
    - name: Install dependencies
        run: |
        pip install sphinx pydata-sphinx-theme sphinx-design sphinx-copybutton sphinx-autoapi
    - name: Sphinx build
        run: |
        sphinx-build docs _build
    - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v3
        if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/main' }}
        with:
        publish_branch: gh-pages
        github_token: ${{ secrets.GITHUB_TOKEN }}
        publish_dir: _build/
        force_orphan: true

• Line 16. Install dependencies

  • This tells GitHub to install sphinx and its dependencies to the ubuntu image.

  • Note: After you add a new sphinx extension to pyproject.toml and to docs/conf.py, you’ll also need to add the dependency to the list on line 16.

• Line 19. Build Docs

  • This runs sphinx-build on the docs/ directory (in the repo) and creates the _build/ directory.

• Line 24. Publish to branch

  • After building the docs, this line tells GitHub to publish the changes to the gh-pages branch.

  • Note: this needs to be the same branch that GitHub Pages is set to publish with.

• Line 26. Specify directory to publish

  • This informs GitHub Pages where the static HTML documentation (built by sphinx-build) is located.

3. Verifying GitHub Workflow Actions

Using the previously mentioned workflow, a GitHub Action will be triggered whenever a commit is pushed to the repo. You can monitor running jobs from your GitHub Repository.

Click on the Actions tab.

Current and previous workflow runs are listed in the Actions tab. The color of the icon indicates the current status of the run. You may notice a pages build and deployment job running. This is reponsible for building the docs.

A red icon indicates that the run has failed. You can click on a run to get debug info for each step. Featured in this figure is a very common error: sphinx is missing an extension because it was not installed in the documentation.yml workflow.

To fix this, sphinx-copybutton had to be added to line 16 in documentation.yml (see 2a. Example Workflow)