Using Sphinx-generated HTML documentation on GitHub project pages

21 Jul 2018 in Programming on Sphinx, Github

It turns out it's a lot easier to publish Sphinx documentation as GitHub Pages than pretty much all google search results on the topic (at the time of this writing…) would have it.

All you need to do is:

1. Not save your Sphinx files in a folder named ./docs under your repo-root.
2. Change the html target in the sphinx-quickstart-generated Makefile to build in the ./docs folder — one of the locations where you can tell GitHub to look for web site material. If, say, you told sphinx-quickstart to have your files in a subdirectory of your repo root, the corresponding lines would look like this:

.PHONY: html
html:
	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) ../docs
	@echo
	@echo "Build finished. The HTML pages are in ../docs."

You can now generate your documentation as always and need to synchronize only one branch with GitHub - no need for shell scripts to be called by make or messing with a separate gh-pages branch. (The branch technique is presumably most useful if you write your documentation by hand, in which case you will simply switch between code and documentation branches, but not for in-code documentation as with autodoc.)