Sphinx + Python on Github Pages / Jekyll

August 20, 2020

Sphinx works great with Github Pages. Sphinx requires one-time setup as described below. The URL will be like https://geospace-code.github.io/pymap3d/.

Install Sphinx in an environment otherwise it may downgrade other packages:

conda create -n sphinx

conda activate sphinx

pip install sphinx

Setup docs using Sphinx Quickstart

sphinx-quickstart

Most defaults are fine, except:

autodoc: automatically insert docstrings from modules (y/n) [n]: y
mathjax: include math, rendered in the browser by MathJax (y/n) [n]: y
viewcode: include links to the source code of documented Python objects (y/n) [n]: y
githubpages: create .nojekyll file to publish the document on GitHub pages (y/n) [n]: y

Add to .gitignore

doctrees/
.buildinfo

Edit docs/Makefile to include

SOURCEDIR     = .
BUILDDIR      = .

Create empty docs/.nojekyll or else Jekyll will reject all directories starting with _, breaking the Sphinx docs.

Edit docs/index.rst to have entries like

.. automodule:: pymap3d
  :members:

.. automodule:: pymap3d.vincenty
  :members:

Create docs/index.html containing only

<html>
<head>
<meta http-equiv="refresh" content="0; url=html/index.html" />
</head>
<body></body>
</html>

Add docs to branch

Select a branch to use for HTML docs under the repo settings page “GitHub Pages” section. Suppose we use branch “html-docs”:

git switch -c html-docs

git add docs/

git commit -am "add html docs"

git push -u origin html-docs

Related: easier to use pdoc Python autodoc generator