Popular tools and solutions

Questions

• What tools are out there?

• What are their pros and cons?

Objectives

• Choose the right tool for the right reason.

---

Documentation Tools: comparison

We try to compare documentation tools in various dimensions:

• Convenience: how easy it is to contribute and set up, for different kinds of people?

• Maintainability and Reproducibility: is it easy to retrieve the information for different versions of the code? Good for tools that can be version-controlled along with the code.
  Even better if correctness of information can be checked automatically (does the output of a snippet of code match the docs?)

• Searchability: is it easy to find the information we need?

• Readability: is it easy to read when rendered? Can one copy-paste from it easily?

• LLM-friendliness: is it convenient to feed to an LLM or an AI-agent?

Comparison of tools for documentation

Type	Convenient	Maintainable/ Reproducible	Searchable	Readable	LLM friendly	Notes
In-code Documentation	✅✅ (P), ❌ (U)	✅🟨	🟨	❌	✅🟨
README	✅	✅🟨	🟨	✅	✅	typically enough
HTML Generators	🟨	✅🟨	✅	✅✅	❌	powerful, only viable option for readable API docs
Wikis	🟨 (P) ✅ (NP)	❌❌	✅	✅	❌
Latex	🟨	❌🟨	🟨	✅ (?)	❌	✅Physics/Math, ❌copy/paste
Jupyter	🟨 🟨/❌	✅✅	🟨 (?)	✅	🟨	✅ validation tooling
llms.txt	🟨	🟨	N/A	🟨/❌	✅✅

Abbreviations in the table:

• P: For Programmers, who live in the code;

• U: For Users;

• NP: For Non-Programmers.

---

HTML static site generators

There are many tools generate documentation that can be viewed locally, or hosted on the web.

Here are some HTML static site generators, relevant in our communities. These tools offer some or all of these features:

• API Reference generation: they read the source code scanning for docstrings, and render them to HTML

• Search: they offer a “whole site” search feature (non trivial, when viewing only one page). (if you can download )

• Validation: check that the code snipped in the documentation match the real behaviour of the code.

• Continuous checks: regenerate automatically every time you save, so that you can catch errors early

PythonRC/C++FortranJuliaRustAny

• Sphinx ← this is how this lesson material is built

  • Generate HTML/PDF/LaTeX from RST and Markdown (MyST)

  • Basically all Python projects use Sphinx but Sphinx is not limited to Python.

  • Read the docs hosts public Sphinx documentation for free!

  • API Reference generation: via autodoc or autoapi

  • Search:

    • limited, keyword-based client-side (Javascript that runs in browser)

    • Full-text server-side on Read the docs

  • Validation: via doctest

• MkDocs: A Markdown-first static site generator (with a vast system of plugins developed independently).

  • API Reference generation: via mkdocstrings

  • Search: search plugin for client-side (Javascript that runs in the browser - lunr.js) Project now (as of 2026) not maintained [1]

• Doxygen:

  • API Reference generation: has also support for Python

---

Hosting Documentation on the Web

GitHub, GitLab, and Bitbucket make it possible to serve HTML pages:

• GitHub Pages

• Bitbucket Pages

• GitLab Pages

Read The Docs is also free to use for open source code, and can be connected to common software forges.

Discussion

Do you know an awesome tool or feature that should be in this list? Let us know! (click on “Edit on GitHub” at the top of this page)

---

Plain Text formats: reStructuredText and Markdown

# This is a section in Markdown   This is a section in RST
                                  ========================

## This is a subsection           This is a subsection
                                  --------------------

Nothing special needed for        Nothing special needed for
a normal paragraph.               a normal paragraph.

                                  ::

    This is a code block          This is a code block


**Bold** and *emphasized*.        **Bold** and *emphasized*.

A list:                           A list:
- this is an item                 - this is an item
- another item                    - another item

There is more: images,            There is more: images,
tables, links, ...                tables, links, ...

• Two of the most popular lightweight markup languages.

• reStructuredText (RST) has more features than Markdown but the choice is a matter of taste.

• There are (unfortunately) many flavors of Markdown.

• Motivation to stick to a standard text-based format: They make it easier to move the documentation to other tools which also expect a standard format, as the project/organization grows.

• We use MyST flavored Markdown in the Sphinx and Markdown episode and the Hosting websites/homepages on GitHub Pages example.

• Nice resource to learn Markdown: Learn Markdown in 60 seconds

• Pandoc can convert between MD and RST (and many other formats).

Keypoints

• READMEs are typically a good starting point

• Some popular solutions make reproducibility and maintenance of multiple code versions difficult.

• The landscape of tools is very diversified and every community has their own favourite.

• The basic functionality of all Static site generators is very similar, but specific aspects (API ref generation, search, validation) differ.

---

[1]

After somewhat dramatic events (2026), MkDocs 1.x is now superseded by Zensical, which tries to keep compatibility with MkDocs 1.x. (MkDocs 2.0 is also being developed but projects and plugins based on 1.x will break).