Sphinx + Python on Github Pages / Jekyll

Related: Easier to use pdoc Python autodoc generator


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

Install Sphinx

  1. setup an environment for Sphinx otherwise it may downgrade other packages:

    conda create -n sphinx
    
    conda activate sphinx
    1. Install Sphinx
    pip install sphinx

setup docs

  1. Use 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
    
    1. add to .gitignore

      doctrees/
      .buildinfo
      
    2. edit docs/Makefile to include

    SOURCEDIR     = .
    BUILDDIR      = .
    
  2. create empty docs/.nojekyll or else Jekyll will reject all directories starting with _, breaking the Sphinx docs.

  3. edit docs/index.rst to have entries like

    .. automodule:: pymap3d
        :members:
    
    .. automodule:: pymap3d.vincenty
        :members:
    1. create docs/index.html containing only
    <html>
    <head>
    <meta http-equiv="refresh" content="0; url=html/index.html" />
    </head>
    <body></body>
    </html>
  4. add the docs directory to Git

    git add docs/
    1. In your Github repo Settings → Github Pages → Source: “master branch /docs folder”
    2. git commit and push. It takes a few seconds for Github Pages to deploy your HTML.