How to write docs with mkdocs

For full documentation visit mkdocs.org.

Basics

  • mkdocs serve - Start the live-reloading docs server locally

Project layout:

mkdocs.yml    # The configuration file.
docs/
    index.md  # The documentation homepage.
    ...       # Other markdown pages, images and other files.

MkDocs are markdown documents, so the answer is easy: just use plain Markdown and, optionally, the supported extensions. More info in the official docs.

Supported extensions

The theme we are using is material, which supports very fancy extensions.

Admonitions

Tip

This is so cool huh? Check all styles here.

!!! tip
    This is so cool huh? Check all styles [here](https://squidfunk.github.io/mkdocs-material/extensions/admonition/#types).

Citations

This is a very important finding.1

This is yet another finding.2

These are written with labels like this:

> This is a very important finding.[^1]

> This is yet another finding.[^Rodríguez-Guerra and Pedregal, 1990]

[^1]: Lorem ipsum dolor sit amet, consectetur adipiscing elit.

[^Rodríguez-Guerra and Pedregal, 1990]: A kid named Jaime.

LaTeX

Either in blocks

\frac{n!}{k!(n-k)!} = \binom{n}{k} * Jaime
$$
\frac{n!}{k!(n-k)!} = \binom{n}{k} * Jaime
$$

or inline:

This my best equation ever: p(x|y) = \frac{p(y|x)p(x)}{p(y)}

This my best equation ever: $p(x|y) = \frac{p(y|x)p(x)}{p(y)}$

Checkboxes

  • Checkbox
  • Checkbox
- [ ] Checkbox
- [X] Checkbox

Emoji

Github shortcuts are supported:

😄 ❤ 👍

:smile: :heart: :thumbsup:

Tabbed fences

This is the step 1
# This is the step 2 with python code highlighting
he = Element("Helium")
This is the step 3

This line interrupts the fences and creates a new block of tabs

# This is the step 4 with python code highlighting
be = Element("Beryllium")

Obtained with:

``` tab="Step 1"

This is the step 1
```

```python tab="Step 2"

# This is the step 2 with python code highlighting
he = Element("Helium")
```

``` tab="Step 3"

This is the step 3
```

This line interrupts the fences and creates a new block of tabs

```python tab="Step 4"

# This is the step 4 with python code highlighting
be = Element("Beryllium")
```

Extra inline markup

Code Result
==hey== hey
~~hey~~ hey
^^hey^^ hey
a^migo^ amigo
-->

Docstrings

We are using mkdocstrings for our docstrings, which deviate slightly from the more popular numpydoc syntax. Instead, it's closer to Google-style docstrings. To sum up, this is a more or less complete example of the requested syntax:

"""
A short description of this function.

A longer description of this function.
You can use more lines.

    This is code block,
    as usual.

    ```python
    s = "This is a Python code block :)"
    ```

Arguments:
    param1: An integer?
    param2: A string? If you have a long description,
        you can split it on multiple lines.
        Just remember to indent those lines with at least two more spaces.
        They will all be concatenated in one line, so do not try to
        use complex markup here.

Note:
    We omitted the type hints next to the parameters names.
    Usually you would write something like `param1 (int): ...`,
    but `mkdocstrings` gets the type information from the signature, so it's not needed here.

Exceptions are written the same.

Raises:
    OSError: Explain when this error is thrown.
    RuntimeError: Explain as well.
        Multi-line description, etc.

Let's see the return value section now.

Returns:
    A description of the value that is returned.
    Again multiple lines are allowed. They will also be concatenated to one line,
    so do not use complex markup here.

Note:
    Other words are supported:

    - `Args`, `Arguments`, `Params` and `Parameters` for the parameters.
    - `Raise`, `Raises`, `Except`, and `Exceptions` for exceptions.
    - `Return` or `Returns` for return value.

    They are all case-insensitive, so you can write `RETURNS:` or `params:`.

__Examples__

Experimental support. You need code fences and an extra blank line at the end
so they can be highlighted _and_ recognized by `pytest`.
Check https://github.com/pawamoy/mkdocstrings/issues/52 for updates.

    ```python
    >>> 2 + 2 == 4
    True

    ```

"""

Real docstring examples

Check docs.developers._docstrings_example and its source code below.


Example module to show how docstrings are written for mkdocs + mkdocstrings

example_function(arg1, kwarg=None)

Show source code in developers/_docstrings_example.py
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
def example_function(arg1, kwarg=None) -> object:
    """
    Example function to demonstrate how APIs are rendered

    Parameters:
        arg1 (dict): Some description for this argument.
            This type (in parenthesis) is ignored.
        kwarg: Some more descriptions

    Returns:
        A description for the returned value

    __Examples__

    This can be automatically tested with `pytest --doctest-modules`!
    Syntax might change subtly in the future.
    Check https://github.com/pawamoy/mkdocstrings/issues/52

    ```python
    >>> 2 + 2 == 4
    True  # this passes pytest
    >>> 2 + 2 == 5
    True  # this fails pytest

    ```
    """
    pass

Example function to demonstrate how APIs are rendered

Parameters

Name Type Description Default
arg1 _empty Some description for this argument. This type (in parenthesis) is ignored. required
kwarg _empty Some more descriptions None

Returns

Type Description
object A description for the returned value

Examples

This can be automatically tested with pytest --doctest-modules! Syntax might change subtly in the future. Check https://github.com/pawamoy/mkdocstrings/issues/52

>>> 2 + 2 == 4
True  # this passes pytest
>>> 2 + 2 == 5
True  # this fails pytest

example_function_with_type_hints(arg1, kwarg=None)

Show source code in developers/_docstrings_example.py
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
def example_function_with_type_hints(arg1: dict, kwarg: typing.Any = None) -> object:
    """
    Example function to demonstrate how APIs are rendered

    Parameters:
        arg1: Some description for this argument.
        kwarg: Some more descriptions

    Returns:
        A description for the returned value

    __Examples__

    This can be automatically tested with `pytest --doctest-modules`!
    Syntax might change subtly in the future.
    Check https://github.com/pawamoy/mkdocstrings/issues/52

    ```python
    >>> 2 + 2 == 4
    True  # this passes pytest
    >>> 2 + 2 == 5
    True  # this fails pytest

    ```
    """
    pass

Example function to demonstrate how APIs are rendered

Parameters

Name Type Description Default
arg1 dict Some description for this argument. required
kwarg Any Some more descriptions None

Returns

Type Description
object A description for the returned value

Examples

This can be automatically tested with pytest --doctest-modules! Syntax might change subtly in the future. Check https://github.com/pawamoy/mkdocstrings/issues/52

>>> 2 + 2 == 4
True  # this passes pytest
>>> 2 + 2 == 5
True  # this fails pytest

  1. Lorem ipsum dolor sit amet, consectetur adipiscing elit. 

  2. A kid named Jaime. 


Last update: April 24, 2020