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:
- Not save your Sphinx files in a folder named
./docsunder your repo-root.
- Change the
htmltarget in the
Makefileto build in the
./docsfolder — one of the locations where you can tell GitHub to look for web site material. If, say, you told
sphinx-quickstartto have your files in a subdirectory of your repo root, the corresponding lines would look like this:
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.)