Hosting Your Documentation on Read the Docs

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

00:55 Can you hear the but coming? They host the documentation for over a hundred thousand different open-source projects and serve 55 million pages a month.

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:28 First off, to publish on Read the Docs, you’ll need a Read the Docs account. When you create an account, you will have the option to connect to a service like GitHub.

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.

02:52 Once you’ve connected to a service, you add a project on the Read the Docs side. Read the Docs doesn’t just assume it’ll be building for all of your repos.

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:16 There is a setting to go to Python 3, but that uses the oldest compatible version of Python 3 supported. At the time of this recording, that’s Python 3.7.

03:26 There’s a control panel on the site, and originally that was how you controlled everything. This still works, but a lot of the newer settings aren’t there.

03:35 Read the Docs introduced a configuration YAML file, which you can include in your project and controls your documentation build settings. The file is called .readthedocs.yaml.

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:00 All the things you can configure on the Web can be configured through the .readthedocs.yaml file as well as much more. This example file is one I use rather frequently. It’s pretty bare-bones.

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.

04:26 In the case of something messy, like one of my Django apps, that means it will be pip installing 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.

04:55 Not only are they hosting hundreds of thousands of projects, but they’re running build scripts for each and every one of them. All that for free. Like I said, these guys are awesome.

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.

05:33 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 django-awl.

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.

06:18 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.

06:32 The fact that they call any of my codes stable can probably be considered generous. Along the top here, the buttons are the things you can do with the project.

06:41 Let’s go to the builds area.

06:45 Here are all the builds that have been run on the project. Let me click on one of the failed ones. And there you go. You can see what went wrong. Let me scroll down a little bit.

06:56 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:17 And now let’s look at a passing build. Here you can see all the things it does. It checks out a repo, creates a virtual environment, and installs a bunch of packages.

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.

07:42 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.

08:02 All right. Well, this isn’t live TV, so I can always do it again, but let’s be brave, and I’ll hit the Build button.

08:16 There it’s checking things out …

08:22 assigning Python 3.9 …

08:27 creating the virtual environment …

08:46 a bunch of pip install on my packages …

08:53 doing the actual Sphinx build … and now it’s uploading it to the IO site. There you go. The build completed.

09:04 Going back to the builds page … and there you see stable and latest passed zero minutes ago. Let’s go to versions, and there they are: latest and stable.

09:17 Let me scroll down a little bit.

09:20 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.

09:46 Since I create feature branches when I work on this library, master and latest will always be the same. Scrolling back up,

09:54 let’s take a quick look at the admin page.

09:59 There’s a lot here,

10:04 and depending on the complexity of your project, you can fine-tune all sorts of things.

10:11 The advanced settings section is what controls how your project is built. Let me click that …

10:29 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.

10:42 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.

11:01 And there you go. The documentation at django-awl.readthedocs.io. All right, that’s it for the whirlwind tour. Hopefully it’s giving you enough of a taste that you can dive in yourself.

11:15 The last lesson, as always, is the summary, and it includes some links to other sources of info like Sphinx cheat sheets as well.