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.

---

In-code documentation

• Comments, function docstrings, …

• Advantages

  • Good for programmers

  • Version controlled alongside code

  • Can be used to auto-generate documentation for functions/classes

• Disadvantage

  • Probably not enough for users of the code

For a closer look at this see the In-code documentation episode.

---

README files

• Advantages

  • Versioned (goes with the code development)

  • It is often good enough to have a README.md or README.rst along with your code/script

• If you use README files, use either RST or Markdown

• A great guide to README files: MakeaREADME

For a closer look at this see the Writing good README files episode.

---

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).

---

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: source code is read, scan for docstrings and render them

• 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.

  • API Reference generation: via mkdocstrings

  • Search: search plugin for client-side (Javascript that runs in the browser - lunr.js)

• Doxygen:

  • API Reference generation: has also support for Python

Discussion

Do you know an awesome tool or feature that should be in this list? Let us know! (Open a PR)

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.

---

Wikis

• Popular solutions (but many others exist):

  • MediaWiki

  • Dokuwiki

• Advantage

  • Barrier to write and edit is low

• Disadvantages

  • Typically disconnected from source code repository (reproducibility)

  • Difficult to serve multiple versions

  • Difficult to check out a specific old version

  • Typically needs to be hosted and maintained

---

LaTeX/PDF

• Advantage

  • Popular and familiar in the physics and mathematics community

• Disadvantages

  • PDF format is not ideal for copy-pasting of examples

  • Possible, but not trivial to automate rebuilding documentation after every Git push

---

Keypoints

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