Deploying Sphinx documentation to GitHub Pages

Objectives

Create a basic workflow which you can take home and adapt for your project.

GitHub Pages 

Serve websites from a GitHub repository
It is no problem to serve using your own URL http://myproject.org instead of http://myuser.github.io/myproject

GitHub Actions 

Automatically runs code when your repository changes
We will run Sphinx build and make the result available to GitHub Pages
Equations and images no problem
Can use Sphinx styles

Typical workflow

Host source code with documentation sources on a public Git repository.
Each time you git push to the repository, a GitHub action triggers to rebuild the documentation.
The documentation is pushed to a separate branch called ‘gh-pages’.

Exercise - Deploy Sphinx documentation to GitHub Pages

gh-pages-1: Deploy Sphinx documentation to GitHub Pages

In this exercise we will create an example repository on GitHub and deploy it to GitHub Pages. The example project contains a script for counting the frequency distribution of words in a given file and some documentation generated using Sphinx. For bigger projects, we can have more source files.

Step 1: Go to the documentation-example project template on GitHub and create a copy to your namespace (“Generate”, since this is a template repository).

Clone the repository

The repository contains following two folders, among few other files:

source folder contains the source code
doc folder contains the Sphinx documentation

The doc folder contains the Sphinx configuration file (conf.py) and the index file (index.rst) and some contents (Markdown files). The conf.py file has been adjusted to be able to autogenerate documentation from sources.

Build HTML pages locally

Inside the cloned repository, build the documentation and verify the result in your browser:

$ sphinx-build doc _build

Test HTML pages links

Inside the cloned repository, check the integrity of all internal and external links:

$ sphinx-build doc -W -b linkcheck -d _build/doctrees _build/html

Step 2: Add the GitHub Action

Create a new file at .github/workflows/documentation.yaml with the contents

name: Docs
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 sphinx_rtd_theme
      - name: Sphinx build
        run: |
          sphinx-build doc _build
      - name: Deploy
        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

You don’t need to understand all of the above, but you might spot familiar commands in the run: sections.

Add, commit and push to GitHub
Check the action at https://github.com/<myuser>/documentation-example/actions. Replace <myuser> with your GitHub username.

Step 2: Enable GitHub Pages

Go to https://github.com/<myuser>/documentation-example/settings/pages
In the “Source” section, choose “Deploy form a branch” in the dropdown menu
In the “Branch” section choose “gh-pages” and “/root” in the dropdown menus and click save
(You should be able to verify the pages deployment in the Actions list)

Verify the result

That’s it! Your site should now be live on https://<myuser>.github.io/documentation-example/ (replace username).

Verify refreshing the documentation

Finally, make some changes to your documentation

Add documentation related to other functions
Prerequisites and how to use the program
Rules for contribution
Some example results (figures, tables, …)
Commit and push them, and verify that the documentation website refreshes after your changes (can take few seconds or a minute)

Do not add the generated build directory to your repository

The _build directory is generated locally with the command sphinx-build doc _build and allows you to check the content locally but it should not be part of the Git repository. We recommend to add _build to .gitignore to prevent you from accidentally adding files below _build to the Git repository.

Alternatives to GitHub Pages

GitLab Pages and GitLab CI can create a very similar workflow.

Read the Docs is the most common alternative to hosting in GitHub Pages.

Sphinx simply builds HTML files, and you can host them anywhere, for example your university’s web space or own web server. This is the whole point of static site generators.

Migrating your own documentation to Sphinx

First convert your documentation to markdown using Pandoc
Create a file index.rst which lists all other RST files and provides the table of contents.
Add a conf.py file. You can generate a starting point for conf.py and index.rst with sphinx-quickstart, or you can take the examples in this lesson as inspiration.
Test building the documentation locally with sphinx-build.
Once this works, follow the above steps to build and deploy to GitHub Pages.

Keypoints

Sphinx makes simple HTML (and more) files, so it is easy to find a place to host them.
Github Pages + Github Actions provides a convenient way to make sites and host them on the web.