As of 2021, the best guide that I have found is here

Hosting project documentation using GitHub pages

Make a sister directory to the project repo so that it doesn’t get commited to your main GitHub repo

Put the ‘HTML’ folder generated by Sphinx (local compile) into this repository

Initialize this directory on GitHub using the standard method

Now create a gh-pages branch and push the changes to that branch as well:

git checkout -b gh-pages
git add .
git push origin gh-pages

This is a less optimal solution because you have to re-copy the entire folder of documentation each time a change is made. I’m still working on a smoother fix.

For example, for my project [pypdb] I go through the following checklist when committing new documentation to the main branch:

  • Remove temporary copies of main file from ipynb directory
  • Export HTML file of all notebooks and put in the right directories
  • Update all documentation:

    • Compile sphinx
    • Retrieve HTML folder from output
    • Put this HTML folder in the Documentation GitHub repository
    • push to master
    • push to gh-pages branch
  • Update version number in
  • push to GitHub
  • Update Github tags
  • Update PyPI
  • Test pip install in a clean environment

Using Sphinx

Install Sphinx and numpydoc:

$ conda install sphinx
$ pip install numpydoc

Navigate to your local repository:

 $ mkdir docs
 $ cd docs
 $ sphinx-quickstart

It’s fine to just accept all the default, but make sure you enable autodoc when you are asked about it.

Edit the file to include an explicit absolute path to the home folder of your module or library:


Make sure includes the following lines:

extensions = [

Navigate to the docs directory and run sphinx:

     $ make html

Format docstrings using .rst styling. Denote headings using :heading:

If make html isn’t picking up changes, try touching various .rst files

$ touch index.rst
$ touch mymodulename.rst

Eventually one of them will force a rebuild. Can also try:

$ sphinx-build -E -b html -d _build/doctrees   . _build/html

Rebuilding documention

Delete all directories beginning with an underscore. Running make clean will delete everything under _build, but the output of extensions like autosummary will not be deleted, which can cause issues.

Using Read The Docs

Acivate a Web Hook in the settings of the GitHub repository so that every commit will update the docs

In the Project Admin page, enable virtualenv and include a requirements.txt file:


Put this file in the root of the documentation, docs/. You may also get an ImportError with autodoc that requires you to put a copy of the repository’s in docs/. Why this is necessary is a profound and uninteresting mystery.

Sphinx with GitHub pages

Follow the instructions in this thread

Key points

  • Add a .nojekyll file to the base docs directory

    touch .nojekyll

  • GitHub will ignore files starting with an underscore. Depending on the contents of .gitignore, files containing the name build may also be ignored. In this case, edit the contents of the sphinx Makefile to point to the new newbuilddirname/html/ directory.

  • Now add a new index.html to the sphinx base directory that redirects to the index.html inside the new build directory


  • Updating my documentation does not update my docs, even when I delete everything

Sphinx builds from the module from the version that is installed in the environment. It does not use the current local; it uses whatever was most recently installed in the environment. See here

Useful links

Sphinx for Dummies