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¶

Advantages
- Good for programmers
- Version controlled alongside code
- Can be used to auto-generate documentation for functions/classes
Disadvantage
- Probably not enough for users

We will have a closer look at this in the In-code documentation episode.

README files¶

Advantage
- 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

We will have a closer look at this in the Writing good README files episode.

reStructuredText and Markdown¶

Two of the most popular lightweight markup languages.
reStructuredText (RST) has more features than Markdown but the choice is a matter of taste.
Markdown convenient for smaller documents, but for larger and more complicated documents RST may be a better option.
There are (unfortunately) many flavors of 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, ...

We will use RST in the Sphinx and reStructuredText episode and Markdown in the Hosting websites/homepages on GitHub Pages example

Experiment with Markdown:

To convert between MD and RST (and many other formats):

Pandoc

HTML static site generators¶

There are many tools that can turn RST or Markdown into beautiful HTML pages:

Sphinx <- we will exercise this, this is how this lesson material is built
- Generate HTML/PDF/LaTeX from RST and Markdown.
- Basically all Python projects use Sphinx but Sphinx is not limited to Python
- Read the docs hosts public Sphinx documentation for free!
Jekyll
- Generates HTML from Markdown.
- GitHub supports this without adding extra build steps.
pkgdown
- Popular in the R community
MkDocs
GitBook
Hugo
Hexo
Zola <- this is what we use for our project website and workshop websites

There are many more …

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

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-paste ability of examples
- Possible, but not trivial to automate rebuilding documentation after every Git push

Doxygen¶

Auto-generates API documentation
Documented directly in the source code
Popular in the C++ community
Has support for C, Fortran, Python, Java, etc., see Doxygen Github Repo
Many keywords are understood by Doxygen: Doxygen special commands
Can be used to also generate higher-level (“human”) documentation
Can be deployed to GiHub/GitLab/Bitbucket Pages

Other tools¶

Fortran
- Fortran Documenter (FORD)
Julia
- Franklin: static site generator
- Documenter.jl

Keypoints

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