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.

pip install Sphinx sphinx-rtd-theme

Now, once you have Sphinx installed:

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 GitHub Actions 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.

Now 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. :-)

Adding Your ReadTheDocs Project as a CircuitPython Subproject

If you're creating documentation for an Adafruit repository, you'll want to add your project as a subproject to the CircuitPython project. Note that you will need access to the CircuitPython project to do this.

Before you do that though, you'll need to add Adabot as a maintainer. 

First, click on the Admin tab. Then, scroll down and click on the tab labeled Maintainers and at the bottom of that tab, enter the name of the user to add, adabot in this case, and press Add.

Now, navigate over to the CircuitPython project, click on Admin, click on Subprojects, click Add Subproject, and select your project. Set the alias to the project name with Adafruit CircuitPython removed.

This guide was first published on Jul 31, 2017. It was last updated on Mar 13, 2024.

This page (Sharing docs on ReadTheDocs) was last updated on Mar 08, 2024.

Text editor powered by tinymce.