Hosting Your Documentation on Read the Docs
In the previous lesson, I showed you how to use the
autodoc extension to automatically incorporate your pydoc strings into your documentation. In this lesson, I’ll be introducing you to Read the Docs, a free hosting service that is commonly used by the Python community.
00:16 Read the Docs is a free service for hosting your documentation. It uses two different URLs, one for the control site, which is readthedocs.org, and another for the actual hosted documentation, which is readthedocs.io.
00:33 When you host docs, you get a subdomain of your choosing at readthedocs.io. The service integrates with GitHub, GitLab, and Bitbucket and will automatically build your documentation when you push your code to your repo. Before going any further, a little aside: I really like this service and am happy it’s part of the community.
01:04 I don’t ever remember the service being down. The hosting side is rock solid. Now here’s the but. Some of the configuration is a little clunky. It feels like one of those developer tools written by and for developers.
01:19 Every once in a while, it seems to just stop automatically building stuff for me or disconnects from my GitHub link, and when this kind of thing happens, I simply sign in, give it a bit of a nudge, and it’s fine again.
01:31 This just isn’t a beginner’s tool, and you want to be somewhat comfortable with the idea of packaging and PyPI before messing around here. It might work out of the box for you, but if it doesn’t, you need a degree of comfort with packaging and debugging because you’re going to have to figure out how to do that inside their system. Along those lines, I’m not going to be doing a step-by-step tutorial for Read the Docs.
01:54 Step-wise instructions don’t tend to age well on the internet. I’m sure you’ve had that experience where you find instructions on a webpage somewhere that’s exactly what you need, only to find out that the menu item it’s telling you to click isn’t there anymore.
02:08 Instead of step by step, I’m going to give you an overview. Read The Docs has a decent tutorial and plenty of instructions, so I really just want to give you a tour so you can see the capabilities and then you can go RTFM. That’s Read the Funky Manual. Search and replace funky with the F-word of your choice as you see fit.
02:37 When you connect to a service, Read the Docs sets up triggers on that service so that it is made aware when you push to your repo. Of course, that means you have to go through an integration step with your repo host. On GitHub, this is done through an OAuth connection.
03:00 You have to add a configuration for any repo whose docs you want to have hosted. As part of creating your project, you will configure it. There are some caveats here. First off, it defaults to Python 2, or at least it did the last time I created a project.
03:47 If it’s present in your project, it will take precedence over any settings you configure on the website. There’s a decent tutorial to get you started with all this if you’re going to create an account.
04:14 The reason I use it is to make sure a more recent version of Python is being used to build my docs. Remember that Sphinx is reading your code, which means it has to have the right version of Python to understand your code.
In the case of something messy, like one of my Django apps, that means it will be
django. When it calls
pip install, it’ll be installing all the dependencies of my project, and although the Python might be 3.7 compatible, the Django might not be, and so you’ve got to make sure you’ve got all the right stuff happening. On the Read the Docs website, you can either manually cause a build or have it automatically happen when you push your code. Think about that for a second.
05:05 Each build causes a new version. You can control what versions are publicly available so your users can get at builds for old releases if you like. The build screen acts as a status screen showing you what builds passed and what failed.
05:20 In the case of a failed build, you can get all the output from the host machine that ran the build and see what went wrong. This can be a bit tricky depending on the cause of the error, and you can get into a “but it works for me on my machine” kind of situation.
My first piece of advice, coming from my own doc builds failing many times: make sure you’re running the right version of Python for your project. So you can see a little bit of real Read the Docs, I’m going to give you a quick tour of one of my own open-source projects that is built there. The project is called
05:53 That’s A-W-L, as in the sharp tool you accidentally poke yourself with when you’re trying to work with leather. Let’s go look at it. When you sign in to Read the Docs, you see a list of the projects that you have configured.
06:07 It also shows what’s passing and what is failing. This one here is a defunct project that I haven’t touched in a while. In fact, I’m kind of surprised it was built as recent as under two years ago.
As I said, let’s go look at
django-awl. I’m going to click on the project for more details. This is the project details page, and it shows you that I have two versions, latest and stable. This is the default.
Looks like it’s a Python version issue. This build was long enough ago that I don’t remember the specifics, but I’m guessing it was when Django dropped Python 3.6, but Read the Docs still supported it. Adding a
.readthedocs.yaml file asking for a more recent version of Python fixed the problem. Let’s go back.
07:30 Going to scroll down a little. These lines are a bit finicky. They are clickable, so you can see the whole result of the command, but when you expand them, the expansion doesn’t include the command.
You kind of have to fiddle a little bit to get it to scroll, and in some cases it can scroll a lot. These
pip installs are putting in everything from my
requirements.txt file, so there’s a bunch of them. Okay, let’s go back to the build menu.
You can see on this page all the tags I’ve used in the past for this project. If I wanted to, I could promote some of these older versions so they were also available on this site. Although
django-awl is open source, it’s a utility set whose primary audience is probably me. As such, the docs here are really for me to remember how things work when I use the library, so I pretty much just use whatever the latest version on master is.
and here you can see what version of Python is being used and whether the project itself gets
pip installed into the virtual environment. In the case of Django projects, that’s necessary in order for Sphinx to be able to import the pydoc properly.
It all goes back to that messy framework stuff I mentioned in the previous lesson. For the most part, I try to stay out of this section now and use the
.readthedocs.yaml file instead. Just before finishing, let me scroll to the top and show you the results.
Become a Member to join the conversation.