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.

Motivation and wishlist

In wishlist.md:

In wishlist.md:

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?

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: please replace with alt text?

    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
$ sphinx-quickstart

The quickstart utility will ask you some questions. For this exercise, you can go with the default answers except to specify a project name, author name, and project release:

> Separate source and build directories (y/n) [n]: <hit enter>
> Project name: <your project name>
> Author name(s): <your name>
> Project release []: 0.1
> Project language [en]: <hit enter>

A couple of files and directories are created:

File/directory

Contents

conf.py

Documentation configuration file

index.rst

Main file in Sphinx

_build/

Directory where docs are built (you can decide the name)

_templates/

Your own HTML templates

_static/

Static files (images, styles, etc.) copied to output directory on build

Makefile

Makefile to build documentation using make

make.bat

Makefile to build documentation using make (Windows)

Makefile and make.bat (for Windows) are build scripts that wrap the sphinx commands, but we will be doing it explicitly.

Let’s have a look at the index.rst file, which is the main file of your documentation:

.. myproject documentation master file, created by
   sphinx-quickstart on Sat Sep 23 17:35:26 2023.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

Welcome to myproject's documentation!
=====================================

.. toctree::
   :maxdepth: 2
   :caption: Contents:


Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

  • We will not use the Indices and tables section now, so remove it and everything below.

  • The top four lines, starting with .., are a comment.

  • The next lines are the table of contents. We can add content below:

.. toctree::
   :maxdepth: 2
   :caption: Contents:

   some-feature.md

Note that some-feature.md needs to be indented to align with :caption:.

We now need to tell Sphinx to use markdown files. To do this, we open conf.py and replace the line:

extensions = []

with this line so that Sphinx can parse Markdown files:

extensions = ['myst_parser']

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

# 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

_static
_templates
conf.py
index.rst
make.bat
Makefile
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 editing conf.py and changing the value html_theme (for instance you can set it to sphinx_rtd_theme (if you have that Python package installed) to have the Read the Docs look).

In sphinx.md:

Sphinx-2: Add more content to your example documentation

  1. Add a entry below some-feature.md labeled another-feature.md (or a better name) to the index.rst file.

  2. Create a file another-feature.md in the same directory as the index.rst file.

  3. Add some content to another-feature.md, rebuild with sphinx-build . _build, and refresh the browser to look at the results.

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

1. item 1
2. item 2
3. item 3
1. item 4
1. 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
```

  • We can also use Jupyter notebooks (*.ipynb) with Sphinx. It requires the myst-nb extension to be installed.

In sphinx.md:

Sphinx-3: Rendering (LaTeX) math equations

Math equations should work out of the box. In some older versions, you might need to edit conf.py and add sphinx.ext.mathjax:

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

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.

In sphinx.md:

(optional) Sphinx-4: Auto-generating documentation from Python docstrings

  1. Write some docstrings in functions and/or class definitions of an example python module:

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

  1. Add a file api.md in the same folder as index.rst, with the following content:

# API reference

## example

```{eval-rst}
.. automodule:: example
   :members:
```

  1. In the file conf.py add 3 lines and modify “extensions”:

# this is a trick to make sphinx find the modules in the parent directory
import os
import sys
sys.path.insert(0, os.path.abspath("."))

extensions = ['myst_parser', "sphinx.ext.autodoc"]

  1. List the api.md file in index.rst.

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

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@v3
      - uses: actions/setup-python@v3
      - 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, but you might spot familiar commands in the run: sections.

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

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

  • You should now be able to verify the pages deployment in the Actions list).

Step 5: Verify the result

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

Step 6: 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)

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.