Read the Docs

A very easy way to publish sphinx docs from a GitHub project is to follow the instructions at Read the Docs on GitHub. Some of those instructions are pasted below.

From github rtfd

Read the Docs hosts documentation for the open source community. It supports Sphinx docs written with reStructuredText, and can pull from your Subversion, Bazaar, Git, and Mercurial repositories.

Documentation for RTD

You will find complete documentation for setting up your project at the Read the Docs site.

Quickstart for GitHub-Hosted Projects

By the end of this quickstart, you will have a new project automatically updated when you push to GitHub.

  1. Create an account on Read the Docs. You will get an email verifying your email address which you should accept within 7 days.
  2. Log in and click on “Import”.
  3. Give your project a name, add the HTTPS link for your GitHub project, and select Git as your repository type.
  4. Fill in the rest of the form as needed and click “Create”.
  5. On GitHub, navigate to your repository and click on “Settings”.
  6. In the sidebar, click on “Web Hooks & Services”, then find and click on the “ReadTheDocs” service.
  7. Check the “Active” setting and click “Update Settings”.
  8. All done. Commit away and your project will auto-update.

Using Sphinx extensions

I am using the sphinxcontrib-fulltoc extension to build my docs and ReadTheDocs kept failing with:

ExtensionError: Could not import extension sphinxcontrib.fulltoc

To solve the problem, I placed the fulltoc.py file from the ../Lib/site-packages/sphinxcontrib subdirectory into the docs/ GitHub subdirectory right next to conf.py. It was then necessary to modify conf.py to use the local name of “fulltoc” instead of the full import path of “sphinxcontrib.fulltoc”:

sys.path.append("../")
sys.path.append(".")  # Needed to find fulltoc

# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
#sys.path.insert(0, os.path.abspath('.'))

# -- General configuration ------------------------------------------------

# If your documentation needs a minimal Sphinx version, state it here.
#needs_sphinx = '1.0'

# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.intersphinx',
    'sphinx.ext.todo',
    'sphinx.ext.ifconfig',
    'fulltoc'
]

I tried to modify my requirements.txt file to include sphinxcontrib-fulltoc, but it never worked out for me.