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

Unlock This Lesson

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

Unlock This Lesson

Documenting Python Projects With Sphinx and Read the Docs (Summary)

Sphinx is a great tool for documenting your Python projects. With it, you can incorporate pydoc comments from your code into your docs and use the reStructuredText (RST) markup language to structure and style your document.

Once you’ve perfected your project documentation, you’ll probably want to host it somewhere. That’s where Read the Docs comes in, offering integration with GitHub, GitLab, and Bitbucket to automatically pull new documentation sources from your repositories and build their Sphinx sources.

In this video course, you’ve learned how to:

  • Write your documentation with Sphinx
  • Structure and style your document with RST syntax
  • Incorporate your pydoc comments into your documentation
  • Host your documentation on Read the Docs

With these skills, you’ll be able to write and maintain effective documentation for your Python projects.

To learn more about Sphinx, check out the following documentation:

You can also refer to the following cheat sheets:

For more information on Read the Docs, you’ll find the following resources useful:

Finally, to turbocharge your documentation workflow, you might enjoy working with ChatGPT.


Sample Code (ZIP)

9.3 MB

Course Slides (PDF)

910.1 KB

00:00 In this last lesson, I’ll summarize the course and point you at places for further investigation.

00:07 In this course, you learned all about Sphinx, the de facto standard for documentation in the Python world. Sphinx can generate many different types of output, but your most likely choice is HTML, or at least mine is. Sphinx is based on RST, but with the right plugin, you can use a Markdown variant if you prefer.

00:27 Sphinx is extensible, and my favorite extension is autodoc, which comes with the main package. This extension adds directives that allow you to read your pydoc comments in your code into the documentation.

00:40 It also has ways of creating cross-references, so when you mention a class or function, that item can be clickable, sending the reader to the appropriate docs.

00:49 It also provides some special tags for documenting function arguments and return values, allowing you to structure the content of the documentation. After showing you Sphinx, I gave a tour of Read the Docs, a free hosting site for your documentation.

01:04 There are over a hundred thousand open-source projects documented there, and the good folks at RTD deserve our appreciation. Read The Docs integrates with three of the most popular code repos, allowing you to have your documentation pages automatically rebuilt when new code is pushed. And each build of the docs is versioned, so you can keep old release docs around for folks using older versions of your packages.

01:30 The best place to learn more about Sphinx is in the Sphinx documentation. All three of these links are on their site. The second and third are direct links to the general RST page and the autodoc extension.

01:43 Most of the markup and directives you want will be in one of those two places.

01:48 Sphinx itself is a deep thing. There is lots of docs, but it can sometimes be a bit of a challenge to find what you’re looking for. As such, there are a bunch of cheat sheets out there to help you along. The top one there is actually mine.

02:02 Drop me a note if you think something should be added or if you find mistake.

02:08 For more information on Read the Docs, see their website or specifically their tutorial documentation. Notice how their tutorial is hosted using their service.

02:19 And finally, episode 354 of the Talk Python podcast digs deep into MyST, the variant of Markdown that is supported by Sphinx as an extension. If you want to learn more about it or its associated tools, you might want to check that out. Even if podcasts aren’t your thing, the landing page for that episode has a bunch of links that may be helpful to you. That’s it for me.

02:44 I hope you found value in this course. Thanks for your attention …

02:51 Miranda.

Alain Rouleau on March 22, 2023

Great introduction to Sphinx and the whole documentation thing.

Very informative, thanks a lot!

Christopher Trudeau RP Team on March 22, 2023

Glad you enjoyed it Alain!

Become a Member to join the conversation.