Enabling on Read the Docs

Read the Docs is an excellent website that hosts Sphinx-generated documentation (including the documentation for this project, which is probably where you are reading it). This document assumes that you already have your project configured on Read the Docs, using their default configuration [1].

As a custom extension, sphinx-git isn’t supported out-of-the-box by Read the Docs, but it is very easy to get it working!

Creating a Documentation Requirements File

The first thing you’ll need to do is create a pip requirements file for your documentation. Create a file containing:


and commit it somewhere in your repository [2] (I will assume it is in requirements/doc.txt for the rest of this document).

Configuring Read the Docs

Navigate to the Read the Docs admin page for your project. This will be of the form https://readthedocs.org/dashboard/<PROJECT NAME>/edit/. Once on this page, you need to do two things:

  • Tick the box under “Use virtualenv”, so that Read the Docs will install our custom documentation requirements, and
  • Enter your documentation requirements file name in the “Requirements file” box (requirements/doc.txt from above).

Submitting the form should cause your project to be rebuilt, now with sphinx-git available!


[1]Follow the Read the Docs getting started guide if you haven’t already.
[2]You should probably pin that requirement to a specific version, but that is outside the scope of this documentation. This is probably a good place to start reading about it: http://nvie.com/posts/pin-your-packages/