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.

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