Image 01

Transneptune

beyond the Kuiper Belt, over the sea

Archive for February, 2018

Getting your docs on Read the Docs

Monday, February 26th, 2018

You’ve seen it before: software projects with lucid and lovely documentation, all available on subdomain.readthedocs.org. So, how do?

Well, the good folks at Read the Docs have made your life very easy. Assuming your documentation’s reStructuredText source is kept in git, and you are OK with pushing it to GitHub, you can get Read the Docs building your documentation for very-near free.

Once you’ve made a repository on GitHub with your docs in it, go to readthedocs.org and sign up or log in. Then, go to your dashboard and select “Import a Project”. Click the plus sign next to the project you want, and you’re done. Every time you push to GitHub, Read the Docs will rebuild your documentation.

But you want more than the basics, right? So let’s talk about what to do if your needs are a little left of center.

If your docs are more than just plain Sphinx, you might need some third-party packages to build them correctly. You may also need a specific Python version. To set either of these, you want a file called readthedocs.yml or .readthedocs.yml, where you can set some values. For this particular case, you probably want to set the python.version and requirements_file keys.

For example:

requirements_file: requirements.txt
python:
  version: 3.6

If your docs are part of a Python package, much of this will get autodetected from the setup.py, but if they’re not, it’s useful to explicitly set them.

I find that it’s very useful to explicitly set a more recent version of Sphinx. Also, if you want to use a custom theme, be sure to throw it in the requirements file.

Another common kind of customization you might want or need is a custom domain. Say you want your docs hosted at https://docs.example.com instead of at https://example-project.readthedocs.org. First, for simple HTTP, there are two steps:

  • Add a CNAME record in your DNS that point to the Read the Docs servers.
  • Add a Domain object in the Project Admin > Domains page for your project on Read the Docs.

For HTTPS, you need to set up some sort of SSL proxy. The full scope of this is outside what I can write here, but using a service like Cloudflare1 to terminate the SSL connection and then proxy to Read the Docs is not a bad approach. If you want to do this by hand yourself, consider Let’s Encrypt as a signing authority for your SSL certificates.

If you want to learn more, you can read the Read the Docs docs.


  1. But not Cloudflare. I cannot endorse them.