Documenting Python Projects With Sphinx and Read the Docs (Overview)
Sphinx is a document generation tool that’s become the de facto standard for Python projects. It uses the reStructuredText (RST) markup language to define document structure and styling, and it can output in a wide variety of formats, including HTML, ePub, man pages, and much more. Sphinx is extendable and has plugins for incorporating pydoc comments from your code into your docs and for using MyST Markdown instead of RST.
Read the Docs is a free document hosting site where many Python projects host their documentation. It integrates with GitHub, GitLab, and Bitbucket to automatically pull new documentation sources from your repositories and build their Sphinx sources.
In this video course, you’ll learn 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 clear, reliable documentation that’ll help your users get the most out of your project.
00:00 Welcome to documenting Python Projects with Sphinx and read the docs. My name is Christopher and I will be your guide. This course is all about the Sphinx Documentation generation tool.
00:11 You’ll be learning about how to use Sphinx to document your projects, the RST Markup language, how to use pydoc comments in your code to add content to your documentation, and finally, the Read the Docs documentation hosting site where you can publish your docs.
00:30 Sphinx is the de facto documentation tool for Python. It’s built on top of the docutils library and uses text-based markup formats to provide styling and structure information to your documents.
00:41 Sphinx has a pluggable interface and one of the extensions it ships with can read pydoc allowing you to build documentation by parsing your code comments.
00:51 You do comment your code, right?
00:53 Read the Docs is a free documentation hosting site that understands Sphinx. With the right configuration, you can automatically pull your documentation source from GitHub or other repos, build it and have it hosted at a custom URL.
01:09 This course has been updated and code in it has been tested using Python 3.13 Sphinx 8.1.3, and the Sphinx read the docs theme 3.0.1
01:23 Let’s get started. The next lesson is on installing Sphinx and using it to build documentation.
Become a Member to join the conversation.