Documentation

pdoc aims to do one thing and do it well: API documentation that follows your module hierarchy, with no configuration. Docstrings are Markdown, and it understands Google and numpydoc styles too. Run pdoc ./demo.py or pdoc my_module_name for a preview in your browser that reloads when you edit the code, then pdoc ./demo.py -o ./docs to export the HTML. Its output is self-contained HTML, and for substantially more complex documentation needs, pdoc's docs recommend Sphinx.

Sphinx focuses on handwritten documentation and turns one set of source files into HTML, a PDF via LaTeX, man pages, and more. Its default markup is reStructuredText, and it can read Markdown through MyST-Parser. Run sphinx-quickstart to set up a source directory with a conf.py, then list your pages in the root document's toctree. make html builds the site, and make latexpdf the PDF. To document your code, autodoc pulls in its docstrings, which you mix with your handwritten pages.

Material for MkDocs is a documentation framework on top of MkDocs, and pip install mkdocs-material installs MkDocs with it. You write Markdown and get a searchable static site, with no HTML, CSS, or JavaScript to know. Run mkdocs new ., then set site_name, site_url, and theme: name: material in mkdocs.yml, and mkdocs serve previews the site as you write. For reference docs from docstrings, try mkdocstrings before switching to Sphinx: Material's alternatives page says it builds on MkDocs and adds Sphinx-like functionality.

Zensical is a static site generator from the creators of Material for MkDocs, with the same batteries-included approach. After pip install zensical, zensical new . creates a docs/ folder, a zensical.toml config, and a GitHub Actions workflow. zensical serve previews as you write, and zensical build writes the static site. It also builds existing MkDocs projects without changes from their mkdocs.yml, and its classic theme variant keeps the Material for MkDocs look.

Diagrams draws cloud system architecture in Python code, so you can track changes to a diagram in version control. It renders with Graphviz, so install Graphviz first, then pip install diagrams. Describe the system in a with Diagram("Web Service", show=False): block and chain nodes with >>. Running python diagram.py saves it as a PNG in your working directory.

Install Sphinx, Material for MkDocs, or Zensical into your project's virtual environment, as each one's docs recommend. The documentation generators here all write static HTML, so publish it from CI. All four document a GitHub Actions workflow that deploys to GitHub Pages: Sphinx, Material for MkDocs, Zensical, and pdoc.