pip install rst2pdf rst2pdf mydocument.rst --stylesheets=custom.style Many teams ask: Why not just use Markdown? The answer lies in the tooling.
# Convert a single file rst2html.py mydoc.rst mydoc.html If you write documentation for Python (or nearly any open-source project), you already know Sphinx . It started as a tool for Python documentation but has since become the de facto standard for complex, multi-page RST projects. rst tools
In the world of technical documentation, simplicity and power often sit at opposite ends of the spectrum. ReStructuredText (RST) is the rare exception—a lightweight markup language that is both human-readable and extraordinarily extensible. But to truly harness RST, you need the right RST tools .
| Feature | RST Tools (Sphinx) | Markdown Tools (MkDocs, Hugo) | | --- | --- | --- | | Cross-references (internal) | Native, robust :ref: | Requires plugins or clumsy IDs | | API doc extraction | autodoc (excellent) | Third-party (e.g., mkdocstrings ) | | Directive system | Extensive, user-extensible | Limited, often platform-specific | | Numbered figures/tables | Built-in | Manual or hacky | | Documentation versioning | Excellent (via RTD) | Varies |
Write your own Sphinx extension. Contribute to rst-lint . Convert your legacy Markdown docs to RST using Pandoc and automate the whole pipeline. pip install rst2pdf rst2pdf mydocument
“I renamed a heading and now my links are broken.” Solution: Sphinx’s nitpicky = True mode will warn you about every unresolved reference.
Add sphinx-autobuild for previews. Add doc8 to CI. Add sphinx.ext.graphviz for diagrams.