Popular tools and solutions
What tools are out there?
What are their pros and cons?
Choose the right tool for the right reason.
Comments, function docstrings, …
Good for programmers
Version controlled alongside code
Can be used to auto-generate documentation for functions/classes
Probably not enough for users
We will have a closer look at this in the In-code documentation episode.
Versioned (goes with the code development)
It is often good enough to have a
README.rstalong with your code/script
A great guide to README files: MakeaREADME
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 MyST flavored Markdown in the Sphinx and Markdown episode and the Hosting websites/homepages on GitHub Pages example
Experiment with Markdown:
To convert between MD and RST (and many other formats):
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!
Also hostable anywhere else, like Github pages.
API documentation possible
Generates HTML from Markdown.
GitHub supports this without adding extra build steps.
Popular in the R community
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:
Popular solutions (but many others exist):
Barrier to write and edit is low
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
Popular and familiar in the physics and mathematics community
PDF format is not ideal for copy-paste ability of examples
Possible, but not trivial to automate rebuilding documentation after every Git push
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
Franklin: static site generator
Quarto converts markdown to websites, pdfs, ebooks and many other things
Some popular solutions make reproducibility and maintenance of multiple code versions difficult.