Sphinx + Python on Github Pages / Jekyll

1 minute read

Sphinx works great with Github Pages, but it requires a little one-time setup as described below. When done, if you have a custom Github Pages domain, the page will have a URL like https://www.scivision.co/pymap3d. For a complete example, see my PyMap3D webpage and repo.

  1. Install Sphinx
    pip install sphinx
    
  2. Use Sphinx Quickstart
    sphinx-quickstart
    

    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

  3. add to .gitignore
    doctrees/
    .buildinfo
    
  4. edit docs/Makefile to include
    SOURCEDIR     = .
    BUILDDIR      = .
    
  5. create empty docs/.nojekyll or else Jekyll will reject all directories starting with _, breaking the Sphinx docs.
  6. edit docs/index.rst to have entries like
    .. automodule:: pymap3d
         :members:
       
    .. automodule:: pymap3d.vincenty
         :members:
    
  7. create docs/index.html containing only
    <html>
    <head>
    <meta http-equiv="refresh" content="0; url=html/index.html" />
    </head>
    <body></body>
    </html>
    
  8. add the docs directory to Git
    git add docs/
    
  9. In your Github repo Settings → Github Pages → Source: “master branch /docs folder”
  10. git commit and push. It takes a few seconds for Github Pages to deploy your HTML.

Tags:

Categories:

Updated:

Leave a Comment