Skip to content

Good practices for writing documentation#

Line numbers for code snippets#

You can add line numbers to code blocks with the following syntax. Note that you can specify the starting line number in cases where you insert a specific part of a file.

Example

This markdown code

```py linenums="5"
def sum(a, b):
    """Returns the sum of a and b"""
    sum_a_b = a + b
    return sum_a_b
```

results like that when rendered. 

5
6
7
8
def sum(a, b):
    """Returns the sum of a and b"""
    sum_a_b = a + b
    return sum_a_b

Highlight line numbers#

You can highlight certain line numbers of your code block with the hl_lines keyword. Note that the numbers for the highlighted lines are relative to your code block, while the total line numbers can start from any number.

Example

This markdown code

```py linenums="5", hl_lines="2 3"
def sum(a, b):
    """Returns the sum of a and b"""
    sum_a_b = a + b
    return sum_a_b
```

results like that when rendered. 

5
6
7
8
def sum(a, b):
    """Returns the sum of a and b"""
    sum_a_b = a + b
    return sum_a_b

File content placeholders#

Inserting code snippets of examples often makes understanding the documentation much easier. However, keeping these code snippets in sync with the content of the files they are referring to can get exhausting and can be easily forgotten.

To avoid this, please use the following syntax for placing a code snippet in the documentation you are writing.

§§§<filename>:<start>:<end>§§§

This will replace the original line in the markdown file with the content of the file <filename> from line <start> to line <end>. The <filename> has to be relative to the root of the umami repository.

The file in the repository will no be changed, but before building the docs, the tool librep will create a rendered copy of the corresponding markdown file.

Using a URL instead of a file from the repository

If you want to link a file that is not present in the umami repo, but you have a URL to that exact file, you can use the following syntax:

§§§url="<url>":<start>:<end>§§§

Note that if you want to link the content of a file living in another gitlab repository, you have to use the link pointing to the raw file content.

Further examples

Below you can find different versions for inserting different parts of the file examples/plotting/plot_rocs.py into your markdown file.

Placeholder Result
§§§examples/plotting/plot_rocs.py§§§ whole file
§§§examples/plotting/plot_rocs.py::§§§ whole file
§§§examples/plotting/plot_rocs.py:10:20§§§ from line 10 to line 20
§§§examples/plotting/plot_rocs.py::10§§§ from top to line 10
§§§examples/plotting/plot_rocs.py:10§§§ from line 10 to bottom
§§§examples/plotting/plot_rocs.py:10:§§§ from line 10 to bottom
Back to top