Documentation in Python Open Source Community¶

When we discuss documentation in the Pyrhon open source community, you’ll probably hear of these terminologies: Docutils, reStructuredText, and Sphinx.

What exactly are these?

reStructuredText¶

Think of reStructuredText as a markup language. You might already be familiar with other markup language such as HTML or Markdown. In Markdown, as you write your text and document, you can specify ways to format or mark up your text, and the Markdown can then be converted into HTML file, which you can later view in the browser.

reStructuredText works the same way. You can write your text with certain formatting and markup, and it can then be converted into HTML for viewing. The file extension is .rst.

reStructuredText predates Markdown. Python has been using reStructuredText since 2002. Markdown only came into existence two years later in 2004.

The Python community saw the need to have better formatting for their docstrings, because the plaintext was not expressive enough.

With the acceptance of PEP 287, reStructuredText was adopted for the use of Python docstrings.

Since then, reStructuredText has been used widely in Python, not just for docstrings, but also in the official Python documentation as well as the PEPs (Python Enhancement Proposals).

Many Python open source libraries are also using reStructuredText to author their documentation, for example: PyPA/packaging, requests, black.

GitHub and GitLab both supports rendering reStructuredText on their web UI. For example, you can create readme.rst on your project, instead of the default readme.md, and it can be rendered accordingly.

Docutils¶

Docutils is the utility tool that can convert plain text documents (including reStructuredText) into other useful formats, like HTML, XML or LaTeX.

Docutils is written in Python and is open source. The only dependency you need in order to use it, is Python itself.

Sphinx¶

If Docutils is the tool that converts reStructuredText into HTML, then Sphinx is like the engine that can take your various documentation files into an intelligent and complete Documentation project.

Sphinx uses Docutils internally to parse reStructuredText. Sphinx has additional features, like: cross-referencing, indexing, and hierarchial structure.

Understanding the tooling like reStructuredText and Sphinx becomes an indispensable skill for any Python open source contributors.

Sphinx and Markdown¶

You can use Markdown with Sphinx, starting in Sphinx 2.1. Please read the documentation on how to configure Sphinx with Markdown.