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