Publish to GitHub pages with Sphinx

I'm a big fan of docs-as-code for more or less any type of content publishing, but I'm less of a fan of Jekyll, the default tool used in GitHub pages. I also prefer ReStructuredText over Markdown as a markup format, so Sphinx is definitely on my shortlist of SSGs (Static Site Generators) for my projects. I recently switched the rst2pdf docs to using Sphinx hosted on GitHub pages, so here are my setup notes.

Basic setup

This project uses Sphinx with a few additions:

Furo theme - a more modern-looking theme than the default that you'll recognise from older websites!
External TOC plugin, to make the navigation sane (The toctree is confusing for me, never mind all the fly-by docs contributors this project wants to be ready for)
Copy button plugin, for easy use of code samples

I also published a list of Sphinx extensions for developer portals which might be interesting if you're setting up your own Sphinx docs project.

Using the basic Furo skeleton as a setup, I moved our existing content (mostly converted with pandoc into the new structure.

Content migration is a whole other blog post so I'll try to avoid that tangent for now.

Build process

Sphinx uses make to build, which is great as it's very widely known, used and supported.
I got everything working locally so that I was sure the content worked and the Sphinx build was all correct and happy.
One thing that I'd recommend is putting all the input content in one folder (not the root - in my case source/) and all the output content in another (I used build/).
The site gets built by a GitHub action, and the new HTML content goes into the build/ folder, then GitHub pages serves the static content from that folder.

The command to build the site is make html - running locally is a good way to work through any errors and fix them.

Sometimes, Sphinx warns about things that aren't important (in this context), so look for the "Build succeeded" message at the end of the output to know if the site did actually build or not.

GitHub workflow

Next, I added the GitHub action to build the site (here's the link to the full workflow, I'm not pasting the whole thing).

The action needs to have write permission, because it's going to build the HTML and commit it to the branch.

Note: this means that if you push a branch, your local branch will be out of date very soon and you should pull down again before you do more work on this branch.

After building the site, you'll also need to deploy it to GitHub pages.

There are a lot of ready-made actions to tie together to make this work, and the GitHub Pages docs are pretty good (just avoid their wizard, it's a quick start with Jekyll).

Overview of how my project workflow works:

actions/checkout@v4
actions/setup-python@v5 Sets up the Python environment.
astral-sh/setup-uv@v3 Sets up the uv package manager that we use in this project.
a step that installs the dependencies and actually builds the site.
actions/configure-pages@v5 Gets GitHub Pages ready.
actions/upload-pages-artifact@v3 Uploads the content that was built in an earlier step as an artifact.
actions/deploy-pages@v4 Actually deploys!

Repository settings

All the settings for GitHub pages are under "Pages" on the left hand navigation of the repository settings area.

Use the "GitHub Actions" option to have everything picked up from the workflow you created (this setting is the default but if you're updating an install that used the old branches pattern, this is is how to change it).

Static sites are here to stay

Well-structured and linked content with metadata serves both human and machine audiences, and static sites help us do that with maximum clarity and efficiency, and minimum hassle. GitHub has a whole set of pages starter sets for you to check out if you prefer Hugo, Astro, or another SSG... what are you waiting for? I'd love to see the links to what you build :)