Documentation

Objectives

• Improve the README of your project or our example project.

Keypoints

• Often a README is enough.

• Documentation which is only in the source code is not enough.

• Documentation needs to be kept in the same Git repository as the code. It evolves with the code.

Why? 💗✉️ to your future self

• You will probably use your code in the future and may forget details.

• You may want others to use your code or contribute (almost impossible without documentation).

Often a README is enough - checklist

• Purpose

• Requirements

• Installation instructions

• Copy-paste-able example to get started

• Tutorials covering key functionality

• Reference documentation (e.g. API) covering all functionality

• Authors and recommended citation

• License

• Contribution guide

See also the JOSS review checklist.

Demonstration

• If we have time, we will improve the README.md of our example repository: https://github.com/coderefinery/planets

What if you need more than a README?

• Write documentation in Markdown (.md) or reStructuredText (.rst) or R Markdown (.Rmd)

• In the same repository as the code -> version control and reproducibility

• Use one of many tools to build HTML out of md/rst/Rmd: Sphinx, MkDocs, Zola, Jekyll, Hugo, RStudio, knitr, bookdown, blogdown, …

• Deploy the generated HTML to GitHub Pages or GitLab Pages

Where to explore more

• Documentation lesson material

• Talk material “Documenting code” by S. Wittke

• Inside Sphinx we can add tables, images, equations, code snippets, … (more information.

• CodeRefinery mini-workshop

Exercises

Exercise Documentation-1: Improve the README of your project

In this exercise we will try to add a README to your project. If you have one already, we will try to improve it by using the checklist above.

If you are unsure where to start, start with one of the checklist items in bold.

Exercise Documentation-2: In-code documentation

Have a look at the following examples and discuss which ones you find useful and which ones you find less useful and why.

Example A:

# now we check if temperature is below -50
if temperature < -50:
    print("ERROR: temperature is too low")

Example B:

# we regard temperatures below -50 degrees as measurement errors
if temperature < -50:
    print("ERROR: temperature is too low")

Example C:

# do not run this code!
# if temperature > 0:
#     print("It is warm")

Example D:

# John Doe: threshold changed from 0 to 15 on August 5, 2013
if temperature > 15:
    print("It is warm")