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 https://myproject.org instead of https://myuser.github.io/myproject.

GitHub Actions

• Automatically runs code when your repository changes.

• We will let it run sphinx-build and make the result available to GitHub Pages.

Our goal: putting it all together

• Host source code with documentation sources on a public Git repository.

• Each time we git push to the repository, a GitHub action triggers to rebuild the documentation.

• The documentation is pushed to a separate branch called ‘gh-pages’.

---

Demonstration - Deploy Sphinx documentation to GitHub/GitLab Pages

GH-Pages-1: Deploy Sphinx documentation to GitHub or GitLab Pages

In this exercise we will create an example repository on a software forge (GitHub or GitLab) and deploy it to the corresponding “Page” service (GitHub pages or GitLab pages)

Preliminary: Verify the “Pages” feature is available on your forge

GitHubGitLab

On github.com, the feature is typically available.

Step 1:

Generate the repository to be used as the starting point. Repositories can be generated from templates, created from imports, or created as empty and filled with a push from you own machine.

GitHubGitLab

In the case of GitHub, the most convenient way is to generate the repository from a template.

Go to the documentation-example project template on GitHub and create a copy to your namespace.

• Give it a name, for instance “documentation-example”.

• You don’t need to “Include all branches”

• Click on “Create a repository”.

Step 2: Browse the new repository.

• The documentation part of the project is in doc/ (many projects do it this way).

• The source code for your project could then go under src/.

Step 3: Automate the generation of the documentation

GitHubGitLab

Add the GitHub Action to your new Git repository.

• Add a new file at .github/workflows/documentation.yml (either through terminal or web interface), containing:

name: documentation

on: [push, pull_request, workflow_dispatch]

permissions:
  contents: write

jobs:
  docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
      - name: Install dependencies
        run: |
          pip install sphinx sphinx_rtd_theme myst_parser
      - name: Sphinx build
        run: |
          sphinx-build doc _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

• You don’t need to understand all of the above – you should mainly pay attention the highlighted lines which are shell commands (we know this because they are part of a run: | section). The first uses pip to install the dependencies and the second runs sphinx-build to actually build the documentation (as we saw in the previous episode).

• After the file has been committed (and pushed), check the action at https://github.com/USER/documentation-example/actions (replace USER with your GitHub username).

Step 4: Enable Pages feature and verify it’s running

GitHubGitLab

• Go to “Settings” -> “Pages”.

• Under “Build and deployment”

  • In the Source section: choose “Deploy from a branch” in the dropdown menu

  • In the Branch section: choose “gh-pages” and “/ (root)” in the dropdown menus and click the Save button.

• You should now be able to verify the pages deployment in the “Actions” list (this is how it looks like for this lesson material).

Step 5: Verify the result

GitHubGitLab

Your site should now be live at https://USER.github.io/documentation-example/ (replace USER).

Step 6 (optional): Verify refreshing the documentation

• Commit some changes to your documentation

• Verify that the documentation website refreshes after your changes (can take few seconds or a minute)

Exercise - Sphinx documentation on GitHub Pages

GH-Pages-2: Putting it all together

1. Follow the above instructions to create a new repository with a Sphinx documentation project;

2. Try adding one or more of the following to your Sphinx project:

   1. API documentation (see exercise in part 1 on API references) which requires the sphinx-autodoc2 package.

   2. a Jupyter notebook (see exercise in part 1 on Jupyter notebooks) which requires the myst-nb package.

   3. change the theme (see the end of the quickstart in part 1). You can browse themes and find their package names on the Sphinx themes gallery.

   Important

   The computer on which the GitHub actions run is not your local machine, and might not have the libraries you need to build the project. Make sure you update the dependencies (installed with pip in the demonstration) appropriately.

   Important

   Make sure the correct file paths are used. This will require adjusting paths from the example from the previous episode to the new layout. Note many paths, including e.g. the autodoc2_packages preference are now relative to the doc/ directory.

What do you need to change in the workflow file?

Solution

1. API documentation

   1. In the workflow/pipeline definition file (.github/workflows/documentation.yml or .gitlab-ci.yml), when calling pip, add the package sphinx-autodoc2 to the list of packages to install.

   2. Follow the instructions in Sphinx-3 changing paths so that:

      1. multiply.py is src/multiply.py and is specified as ../src/multiply.py in the autodoc2_packages preference in conf.py

      2. conf.py is doc/conf.py

      3. index.md is doc/index.md.

   3. Commit and push your changes, verify the action has run successfully, and view the built site in your browser.

2. a Jupyter notebook

   1. In the workflow/pipeline definition file (.github/workflows/documentation.yml or .gitlab-ci.yml), when calling pip, add the package myst-nb to the list of packages to install.

   2. Follow the instructions in Sphinx-4 changing paths so that:

      1. flower.md is doc/flower.md

      2. conf.py is doc/conf.py

      3. index.md is doc/index.md.

   3. Commit and push your changes, verify the action has run successfully, and view the built site in your browser.

3. change the theme

   1. In the workflow/pipeline definition file (.github/workflows/documentation.yml or .gitlab-ci.yml), when calling pip, and add the theme package if necessary.

   2. In doc/conf.py change html_theme = 'sphinx_rtd_theme' to the name of your chosen theme.

   3. Commit and push your changes, verify the action has run successfully, and view the built site in your browser.

Alternatives to GitHub and GitLab pages

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

• Sphinx builds HTML files (this is what static site generators do), and you can host them anywhere, for example your university’s web space or own web server.

Migrating your own documentation to Sphinx

• First convert your documentation to Markdown using Pandoc.

• Create a file index.rst which lists all other Markdown 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 or some other web space.

---

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.