List of exercises

Full list

This is a list of all exercises and solutions in this lesson, mainly as a reference for helpers and instructors. This list is automatically generated from all of the other pages in the lesson. Any single teaching event will probably cover only a subset of these, depending on their interests.

In-code documentation

In in-code-documentation.md:

In-code-1: Comments

Let’s take a look at two example comments (comments in Python start with #):

Comment A

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

Comment B

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

Which of these comments is more useful? Can you explain why?

Solution

Comment A describes what happens in this piece of code. This can be useful for somebody who has never seen Python or a program, but for somebody who has, it can feel like a redundant commentary.
Comment B is probably more useful as it describes why this piece of code is there, i.e. its purpose.

Writing good README files

In writing-readme-files.md:

Exercise README-1: Have fun testing some README features you may not have heard about

Test the effect of adding the following to your GitHub README (read more):

> [!NOTE]
> Highlights information that users should take into account, even when skimming.

> [!IMPORTANT]
> Crucial information necessary for users to succeed.

> [!WARNING]
> Critical content demanding immediate user attention due to potential risks.

For more detailed descriptions which you don’t want to show by default you might find this useful (please try it out):

<details>
<summary>
Short summary
</summary>

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod
tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam,
quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo
consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse
cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non
proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
</details>

Would you like to add a badge like this one: ?

Badge that links to a website (see also https://shields.io/):

[![please replace with alt text](https://img.shields.io/badge/anytext-youlike-blue)](https://example.org)

Badge without link:

![please replace with alt text](https://img.shields.io/badge/anytext-youlike-blue)

Know about other tips and tricks? Please share them (send a pull request to this lesson).

In writing-readme-files.md:

Exercise README-2: Draft or improve a README for one of your recent projects

Try to draft a brief README or review a README which you have written for one of your projects.

You can do that either by screensharing and discussing or working individually.
Use the checklist which we have discussed earlier.
Think about the user (which can be a future you) of your project, what does this user need to know to use or contribute to the project? And how do you make your project attractive to use or contribute to?
(Optional): Try the https://hemingwayapp.com/ to analyse your README file and make your writing bold and clear.
Please note observations and recommendations in the collaborative notes.

In writing-readme-files.md:

Exercise README-3: Review and discuss a README of a project that you have used

In this exercise we will review and discuss a README of a project which you have used. You can also review a library which is popular in your domain of research and discuss their README.

You can do that either by screensharing and discussing or working individually.
When discussing other people’s projects please remember to be respectful and constructive. The goal of this exercise is not to criticize other projects but to learn from other projects and to collect the aspects that you enjoyed finding in a README and to also collect aspects which you have searched for but which are sometimes missing.
Please note observations and recommendations in the collaborative notes.

Sphinx and Markdown

In sphinx.md:

Sphinx-1: Generate the basic documentation template

Create a directory for the example documentation, step into it, and inside generate the basic documentation template:

$ mkdir doc-example
$ cd doc-example

We create the basic structure of the project manually.

File/directory	Contents
conf.py	Documentation configuration file
index.md	Main file in Sphinx

Let’s create the index.md with this content:

# Documentation example with Sphinx

A small example of how to use Sphinx and MyST 
to create easily readable and aesthetically pleasing
documentation.

```{toctree}
:maxdepth: 2
:caption: Contents:
some-feature.md
```

Note that indentation and spaces play a role here.

We also create a conf.py configuration file, with this content:

project = 'Test sphinx project'
author = 'Alice, Bob'
release = '0.1'            
                                                                                
extensions = ['myst_parser']
                                                                                
exclude_patterns = ['_build']

For more information about the configuration, see the Sphinx documentation.

Let’s create the file some-feature.md (in Markdown format) which we have just listed in index.md:

# Some feature

## Subsection

Exciting documentation in here.
Let's make a list (empty surrounding lines required):

- item 1

  - nested item 1
  - nested item 2

- item 2
- item 3

We now build the site:

$ ls -1

conf.py
index.md
some-feature.md

$ sphinx-build . _build

... lots of output ...
build succeeded.

The HTML pages are in _build.

$ ls -1 _build

_sources
_static
genindex.html
index.html
objects.inv
search.html
searchindex.js
some-feature.html

Now open the file _build/index.html in your browser.

Linux users, type:
```
$ xdg-open _build/index.html
```
macOS users, type:
```
$ open _build/index.html
```
Windows users, type:
```
$ start _build/index.html
```
If the above does not work: Enter file:///home/user/doc-example/_build/index.html in your browser (adapting the path to your case).

Hopefully you can now see a website. If so, then you are able to build Sphinx pages locally. This is useful to check how things look before pushing changes to GitHub or elsewhere.

Note that you can change the styling by adding the line

html_theme = "<my favorite theme>"

in conf.py. For instance you can usesphinx_rtd_theme to have the Read the Docs look (make sure the sphinx_rtd_theme python package is available first)

In sphinx.md:

Sphinx-2: Add more content to your example documentation

Add a entry below some-feature.md labeled another-feature.md (or a better name) to the index.md file.
Create a file another-feature.md in the same directory as the index.md file.
Add some content to another-feature.md, rebuild with sphinx-build . _build, and refresh the browser to look at the results.
Use the MyST Typography page as help.

Experiment with the following Markdown syntax:

*Emphasized text* and **bold text**
Headings:

# Level 1

## Level 2

### Level 3

#### Level 4

An image: ![alt text](image.png)
[A link](https://www.example.org)
Numbered lists (numbers adjusted automatically):

item 1
item 2
item 3
item 4
item 5

Simple tables:

| No.  |  Prime |
| ---- | ------ |
| 1    |  No    |
| 2    |  Yes   |
| 3    |  Yes   |
| 4    |  No    |

Code blocks:

The following is a Python code block:
```python
  def hello():
      print("Hello world")
```

And this is a C code block:
```c
#include <stdio.h>
int main()
{
    printf("Hello, World!");
    return 0;
}
```

You could include an external file (here we assume a file called “example.py” exists; at the same time we highlight lines 2 and 3):

```{literalinclude} example.py
:language: python
:emphasize-lines: 2-3
```

Math equations with LaTeX should work out of the box. Try this (result below):

This creates an equation:
```{math}
a^2 + b^2 = c^2
```

This is an in-line equation, {math}`a^2 + b^2 = c^2`, embedded in text.

This creates an equation:

\[a^2 + b^2 = c^2\]

This is an in-line equation, $a^2 + b^2 = c^2$, embedded in text.

Older versions of Sphinx

In some older versions, you might need to edit conf.py and add sphinx.ext.mathjax:

extensions = ['myst_parser', 'sphinx.ext.mathjax']

In sphinx.md:

Sphinx-3: Auto-generating documentation from Python docstrings

Write some docstrings in functions and/or class definitions to a python module multiply.py:

def multiply(a: float, b: float) -> float:
    """
    Multiply two numbers.

    :param a: First number.
    :param b: Second number.
    :return: The product of a and b.
    """
    return a * b

In the file conf.py add autodoc2 to the “extensions”, and add the list autodoc2_packages which will mention "multiply.py":

extensions = ['myst_parser', "autodoc2"]

autodoc2_packages = [
    "multiply.py"
]

If you already have extensions from another exercise, just add "autodoc2" to the existing list.

Add apidocs/index to the toctree in index.md.

```{toctree}
:maxdepth: 2
:caption: Contents:

...
apidocs/index

Re-build the documentation and check the “API reference” section.

In sphinx.md:

Sphinx-4: Writing Sphinx content with Jupyter

For simplicity, create a text-based notebook files flower.md in the same directory as the index.md file. This file will be converted to a Jupyter notebook by the myst_nb Sphinx extension and then executed by Jupyter. Fill the file with the following content:

---
file_format: mystnb
kernelspec:
  name: python3
---
# Flower plot

```{code-cell} ipython3
import matplotlib.pyplot as plt
import numpy as np

fig, ax = plt.subplots(1, 1, figsize=(5, 8), subplot_kw={"projection": "polar"})
theta = np.arange(0, 2 * np.pi, 0.01)
r = np.sin(5 * theta)
ax.set_rticks([])
ax.set_thetagrids([])
ax.plot(theta, r);
ax.plot(theta, np.full(len(theta), -1));
```

Note that there needs to be a title in the notebook (a heading starting with a single #), that will be used as an entry and link in the table of content. 2. In the file conf.py modify extensions to remove "myst_parser" and add "myst_nb" (you will get an error if you include both):

extensions = ["myst_nb"]

Note that MyST parser functionality is included in MyST NB, so everything else will continue to work as before.

List flower in the toctree in index.md.

```{toctree}
:maxdepth: 2
:caption: Contents:
...
flower.md
```

Re-build the documentation and check the “Flower” section.
Alternatively, you can directly add .ipynb files saved from Jupyter notebook or Jupyter lab. Just make sure to list it in the toctree in index.md with the correct path.

If you have problems, consider cleaning manually the jupyter_execute directory.

Deploying Sphinx documentation to GitHub Pages

In gh_workflow.md:

GH-Pages-1: Deploy Sphinx documentation to GitHub Pages

In this exercise we will create an example repository on GitHub and deploy it to GitHub Pages.

Step 1: Go to the documentation-example project template on GitHub and create a copy to your namespace.

Give it a name, for instance “documentation-example”.
You don’t need to “Include all branches”
Click on “Create a repository”.

Step 2: Browse the new repository.

It will look very familar to the previous episode.
However, we have moved the documentation part under doc/ (many projects do it this way). But it is still a Sphinx documentation project.
The source code for your project could then go under src/.

Step 3: Add the GitHub Action to your new Git repository.

Add a new file at .github/workflows/documentation.yml (either through terminal or web interface), containing:

name: documentation

on: [push, pull_request, workflow_dispatch]

permissions:
  contents: write

jobs:
  docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
      - name: Install dependencies
        run: |
          pip install sphinx sphinx_rtd_theme myst_parser
      - name: Sphinx build
        run: |
          sphinx-build doc _build
      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v3
        if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/main' }}
        with:
          publish_branch: gh-pages
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: _build/
          force_orphan: true

You don’t need to understand all of the above – you should mainly pay attention the highlighted lines which are shell commands (we know this because they are part of a run: | section). The first uses pip to install the dependencies and the second runs sphinx-build to actually build the documentation (as we saw in the previous episode).
After the file has been committed (and pushed), check the action at https://github.com/USER/documentation-example/actions (replace USER with your GitHub username).

Step 4: Enable GitHub Pages

On GitHub go to “Settings” -> “Pages”.
Under “Build and deployment”
- In the Source section: choose “Deploy from a branch” in the dropdown menu
- In the Branch section: choose “gh-pages” and “/ (root)” in the dropdown menus and click the Save button.
You should now be able to verify the pages deployment in the “Actions” list (this is how it looks like for this lesson material).

Step 5: Verify the result

Your site should now be live on https://USER.github.io/documentation-example/ (replace USER).

Step 6 (optional): Verify refreshing the documentation

Commit some changes to your documentation
Verify that the documentation website refreshes after your changes (can take few seconds or a minute)

In gh_workflow.md:

GH-Pages-2: Putting it all together

Follow the above instructions to create a new repository with a Sphinx documentation project;
Try adding one or more of the following to your Sphinx project:
1. API documentation (see previous exercise on API references) which requires the sphinx-autodoc2 package.
2. a Jupyter notebook (see previous exercise on Jupyter notebooks) which requires the myst-nb package.
3. change the theme (see the end of the quickstart). You can browse themes and find their package names on the Sphinx themes gallery.
Important

The computer on which the GitHub actions run is not your local machine, and might not have the libraries you need to build the project. Make sure you update the dependencies (installed with pip in the demonstration) appropriately.

Important

Make sure the correct file paths are used. This will require adjusting paths from the example from the previous episode to the new layout. Note many paths, including e.g. the autodoc2_packages preference are now relative to the doc/ directory.

What do you need to change in the workflow file?

Solution

API documentation
1. Change line 16 of .github/workflows/documentation.yml from pip install sphinx sphinx_rtd_theme myst_parser to pip install sphinx sphinx_rtd_theme myst_parser sphinx-autodoc2.
2. Follow the instructions in Sphinx-3 changing paths so that:
  1. multiply.py is src/multiply.py and is specified as ../src/multiply.py in the autodoc2_packages preference in conf.py
  2. conf.py is doc/conf.py
  3. index.md is doc/index.md.
3. Commit and push your changes, verify the action has run successfully, and view the built site in your browser.
a Jupyter notebook
1. Change line 16 of .github/workflows/documentation.yml from pip install sphinx sphinx_rtd_theme myst_parser to pip install sphinx sphinx_rtd_theme myst_parser myst-nb.
2. Follow the instructions in Sphinx-4 changing paths so that:
  1. flower.md is docs/flower.md
  2. conf.py is doc/conf.py
  3. index.md is doc/index.md.
3. Commit and push your changes, verify the action has run successfully, and view the built site in your browser.
change the theme
1. Change line 16 of .github/workflows/documentation.yml and add the theme package if necessary.
2. In docs/config.py change html_theme = 'sphinx_rtd_theme' to the name of your chosen theme.
3. Commit and push your changes, verify the action has run successfully, and view the built site in your browser.

Motivation and wishlist

In wishlist.md:

Our motivation (but let us brainstorm first)

You will probably use your code in the future and may forget details.
You may want others to use your code (almost impossible without documentation).
You may want others to contribute to the code.
Shield your limited time and let the documentation answer FAQs.

In wishlist.md:

Our wishlist (but let us brainstorm first)

Versions

Your code project should be versioned (version control).
Enable reproducibility and avoid confusion: documentation should be versioned as well.
Have you ever seen: “We will soon release a new version and are updating the documentation. Some features may not be available in the version you have downloaded.”?

Documentation should be placed and tracked close to the source code

Documenting close to the source code (e.g. subdirectory doc/) minimizes barrier to contribute.
I should not need to log in to another machine or service and jump through hoops to contribute.
It is often good enough to have a README.md or README.rst along with your code/script.

Use a standard markup language

Markup

Markup is a set of human readable instructions that is used to tell the computer how a document shall be styled and structured. By using a markup language we can for example write a * or - where we want a bullet point to appear in the rendered document.

offers formatting flexibility, enforces a basic document structure and the rendered documents can be exported to other formats (e.g. for printing). Also, the source can be read by humans without knowledge of the language in case the rendered document is unavailable.
We suggest to use either reStructuredText (RST) or Markdown markup.
GitHub and GitLab automatically render README.md or README.rst files.

Copy-paste-able

PDF alone is not enough since copy-pasting out of a PDF document can be difficult.
It is OK to provide a generated PDF in addition to a copy-paste-able format.

Written by humans

Automatically generated documentation (e.g. API documentation) is useful as complementary documentation but it does not replace tutorials written by humans.

Installation instructions

Give step by step instructions for the basic case. Additional information and caveats can be linked from there.
List requirements and dependencies (libraries, compilers, environment).
Include instructions for how to test for correctness after installation.

Make the license explicit

Include a LICENSE file with your source code.
Without a license, your work is under exclusive copyright by default: others are not allowed to re-use or modify anything.
GitHub and GitLab allows to choose a license from common license templates.

Information for contributors

Make it easy for others to contribute: document how you prefer others to contribute.
Users of your code may be shy to contribute code. Your documentation provides a platform for your first contributions.

Hosting websites/homepages on GitHub Pages

In gh-pages.md:

GH-Pages-2: Host your own github page

Deploy own website reusing a template:
- Follow the steps from GitHub Pages https://pages.github.com/. The documentation there is very good so there is no need for us to duplicate the screenshots.
- Select “Project site”.
- Select “Choose a theme”.
- Follow the instructions on https://pages.github.com/.
- Browse your page on https://USERNAME.github.io/REPOSITORY (adjust “USERNAME” and “REPOSITORY”).
Make a change to the repository after the webpage has been deployed for the first time.
Please wait few minutes and then verify that the change shows up on the website.