Sharing docs on ReadTheDocs

Great documentation is a key component of a successful open source library. Luckily, after a little setup, its super easy to write and maintain great docs.

Sphinx

First, you should install Sphinx. Sphinx allows you to build the docs locally to ensure there aren't any documentation errors when you push to your repository.

Download: file
pip install Sphinx sphinx-rtd-theme

Now, once you have Sphinx installed:

Download: file
cd docs
sphinx-build -E -W -b html . _build/html

This will output the documentation to docs/_build/html. Open the index.html in your browser to view them. It will also (due to -W) error out on any warning like Travis will. This is a good way to locally verify it will pass.

ReadTheDocs

ReadTheDocs is another free hosting service used by many open source projects. It integrates with GitHub so that every time new code or docs are pushed to your GitHub, the nicely formatted versions hosted by ReadTheDocs are also updated.

Lets get it setup! First, sign up and login if you don't already have an account. After signing in, your dashboard will be displayed.

On the dashboard click Import a Project and select Import Manually.

For the next page we'll need the https version of our GitHub repository so we go grab it by clicking Clone or Download on the repo front page and selecting Use HTTPS.

Then press the copy icon.

And paste it into the Repository URL field in ReadTheDocs. The name should be Adafruit CircuitPython Example. Then click next.

If you created your ReadTheDocs account and linked your GitHub (like I have below) then it should be able to automatically connect GitHub to itself by creating a Webhook. This Webhook is how ReadTheDocs gets updates from GitHub.

On the right hand side you should also see links to your documentation that you can use to link others to it.

If it didn't automatically create a webhook for you, then you'll need to add ReadTheDocs integration to your GitHub repo manually by going to Settings -> Integrations & Services from your repo. On the right there will be an Add service button that you click and select ReadTheDocs for a long list. Search for "read" to shorten the list.

Then its as simple as clicking Add service.

The next page confirms the service was added by confirming the webhook (aka hook) was created and also listing ReadTheDocs in the Services.

After that, we go back to ReadTheDocs and refresh. We see that its been built successfully on the right and at the top we can view the docs.

Now, as a last step, lets make sure our docs look as expected by clicking the View Docs button.

Awesome! By default it shows our README.rst (didn't I say it was important?). Furthermore, the lefthand side has a link with our module's name. Lets click it to see the module's documentation.

Yay! Everything looks good. This is exactly as we've defined in our Python file. For now, docs are done. :-)

This guide was first published on Jul 31, 2017. It was last updated on Jul 31, 2017. This page (Sharing docs on ReadTheDocs) was last updated on Dec 05, 2019.