Join us and get access to thousands of tutorials and a community of expert Pythonistas.

This lesson is for members only. Join us and get access to thousands of tutorials and a community of expert Pythonistas.

Unlock This Lesson

Hosting Your Documentation on Read The Docs

Documenting Python Projects With Sphinx and Read The Docs - Archived Mahdi Yusuf 04:01

Learn how to upload your documentation to Read The Docs. You’ll see how to use the Read The Docs dashboard to import a project hosted on GitHub. The lesson will also show you how to create a post commit hook in GitHub to automatically build and update the documentation on Read The Docs.

The final part of the lesson is an overview of what you have learned in this course:

Building documentation from scratch
Creating a Sphinx configuration
Adding templates and structure for your documentation
Styling and formatting documentation
Adding a post commit hook to automatically update documentation when new code is pushed.

Congratulations, you made it to the end of the course! What’s your #1 takeaway or favorite thing you learned? How are you going to put your newfound skills to use? Leave a comment in the discussion section and let us know.

00:00 What you simply need to do is log into readthedocs.org and you need to go to your dashboard. You’ll be presented with a dashboard. Currently, all I have is delorean for my projects that are using the documentation at Read the Docs.

00:12 What I would do for a new project is I’d go Import. We’d give the Name, the project name. We’re going to call it doctut. We’re going to paste in the GitHub repository. So, we took our repository here.

00:22 And as you can see, this repository has no documentation as of now. So what we’ll do is we’ll push the code that we have currently and it should create documentation for us on Read the Docs. Once this is done, all we need to do is add a description, documentation for creating amazing documentation.

00:48 Once we have all that, we have our…

00:53 The configuration file, in our particular case, is docs/conf.py.

01:01 Public, we’re going to allow everybody to see our documentation. Version level, Public. We’re going to let everybody see that. We don’t need a virtual env, we don’t need any system packages, we don’t have a requirement file.

01:13 We don’t want to put in analytics code. So, let’s go ahead and create this.

01:18 So, it said it’s going to take a while for us to go build the docs. This obviously won’t work because this project doesn’t have any documentations folder. What we need to do is create a post-commit hook.

01:27 This is easily done through GitHub. What we’re going to do is go to our repository. We’re going to go to Settings. We’re then going to go to Service Hooks. As you can see, we should be able to find Read the Docs in here immediately.

01:40 So we’re going to click this. We’re going to click Active. And we’re going to update our settings. Now our service hook has been created for doctut, so all we need to do now is commit all our changes.

01:55 What I’m first going to do is clean up our docs/ directory, so we’re going to go into the docs/ directory.

02:06 We’re going to make clean. We’ve deleted all our builds, so we only have our source/ directory and whatnot with us. We’re going to back out. We’re going to go git add docs/ , git commit -am 'adding first commit for documentation', and we’re going to push this to GitHub.

02:34 So as you can see, this would have been pushed to our GitHub repository here with all our documentation and whatnot, and we should see a build firing. So, that first one failed.

02:46 I managed to pinpoint the mistake that we made previously, which is quite ironic. Since I was trying to be explicit, I made a mistake. Our conf.py is in docs/source/conf.py.

02:57 So, in order to make this work, we have to make this change to make the path docs/source/conf.py. If you want, you can leave it implicitly and Read the Docs will find the conf.py for you and run against it.

03:10 Now that we have made that change, if we were to go ahead and Submit, our documentation should build and we should be able to see it here. There you have it. So, it may look different from what I was building against locally.

03:23 Locally, we’re using the default Sphinx theme. When you push your code up to Read the Docs and you don’t specify your theme, it’ll use the default Read the Docs theme, which is mobile-ready and quite awesome.

03:36 So, what we’ve covered today is building your documentation from scratch, creating your conf.py, adding templates, and creating a structure for your documentation, styling it, as well as creating a post-commit hook on your repository so when you push code your documentation is rebuilt to reflect your latest code changes.

03:55 I hope you enjoyed the screencast, and happy documenting!

Florian Dahlitz RP Team on March 27, 2019

Hey Mahdi Yusuf,

First of all I want to thank you for this tutorial. As many people (including me) are preferring to use Markdown over reStructured Text, I wanna ask you if it’s possible to add a section about how to properly extend sphinx to support Markdown as well. Certain extensions of projects already exist, but maybe you can give some guidance on that.

Thanks again for creating this! Florian

Dan Bader RP Team on March 27, 2019

@Florian: I’ll chime in for Mahdi here—explaining how to use Sphinx with Markdown support is a great idea for extending this course or adding a new set of lessons, so thanks for that.

In the meantime, you might find this helpful:

www.sphinx-doc.org/en/master/usage/markdown.html

Evan E on May 28, 2019

Read the docs is giving me a build fail with an error of Sphinx error contents.rst is not found? How can I fix this to get the doctut up on read the docs?

Peter on June 27, 2019

Now that we know how to add the license information into our documentation: Will there be a Documenting Python Projects Part II that actually shows how to get the Python code docstrings well structured into html? I always thought this is the basic idea behind Sphinx.

PatrickB on Dec. 6, 2019

This tutorial is a good, basic overview of Sphinx.

Another course on restructuredtext (RST), which is closely tied to Python would be useful.

Thanks.

Ghani on Oct. 20, 2020

Thanks for this very useful tutorial!

Become a Member to join the conversation.