What We Can Learn from Exemplary Python Documentation

Let us build on examples from NumPy, pandas, and Matplotlib to explore techniques and tools with the Sphinx documentation generator. Learn how to implement styles, include advanced elements, and overcome challenges in creating clear, maintainable docs. 📑✨

Set up Sphinx documentation generator, which I can provide in written form beforehand.

If you’ve attended one of last year’s Python conferences in Europe, you might have seen my talk “Documenting Python Code”, where I introduced attendees to the basics of Python documentation. This year, I will expand on that foundation by looking at what can be learned from exemplary Python documentation.

Building on renowned examples from popular Python libraries such as NumPy, pandas, and Matplotlib, this workshop will delve into techniques and tools that help streamline documentation creation while improving clarity and usability. The topics covered include:

Sphinx documentation generator • use reStructuredText as a markup language • simplify docstrings with the NumPy and Google format • generate function and method documentation with sphinx-apidoc

How to • include code snippets as examples and display them in environment-specific tabs • adopt themes and implement appealing styles • use admonitions to highlight important content • write sophisticated mathematical formulas • create versatile diagrams with Kroki • generate interactive HTML documentation with embedded notebooks

Comparison: AsciiDoc vs. Sphinx • explore their strengths and limitations for multi-language projects • see how AsciiDoc can document APIs by including tagged source code snippets

This workshop provides practical insights and examples to help developers, technical writers, and maintainers create better documentation and improve their workflows. Whether you are just starting out or refining an established project, this session will provide actionable techniques to overcome common challenges and take your documentation to the next level.