Writing Documentation for MedModels#
1. Documenting Code#
To ensure that the code documentation for the MedModels package is clear, comprehensive, and automatically generated by Sphinx, follow these guidelines for writing docstrings. Note that the package uses Google style docstrings and supports Sphinx and RST syntax.
2. Working on the Documentation#
First, ensure you have checked out medmodels and installed the documentation environment by executing make install-docs from the repository root.
You can serve the documentation live while developing locally to verify that changes to the docstrings are rendered correctly. To do this, simply run make docs-serve. This command will serve the documentation and automatically refresh and rebuild the local documentation page whenever changes are saved to any of the package or documentation files.
By calling make docs-clean, you can delete all generated docs files again.
3. Structuring Docstrings#
A well-structured docstring should include the following sections in this order:
3.1. Summary Line#
The summary line provides a brief description of what the function or class does. It should be a single line ending with a period. The summary needs to be on the same line as the opening """.
Example:
"""Example module with docstrings for the developer guide."""
from __future__ import annotations
from typing import Any, Dict, Iterator, List, Optional, Tuple, Union
def example_function_args(
param1: int,
param2: Union[str, int],
optional_param: Optional[List[str]] = None,
*args: Union[float, str],
**kwargs: Dict[str, Any],
) -> Tuple[bool, List[str]]:
"""Example function with PEP 484 type annotations and PEP 563 future annotations.
This function shows how to define and document typing for different kinds of
arguments, including positional, optional, variable-length args, and keyword args.
Args:
param1 (int): A required integer parameter.
param2 (Union[str, int]): A parameter that can be either a string or an integer.
optional_param (Optional[List[str]], optional): An optional parameter that
accepts a list of strings. Defaults to None if not provided.
*args (Union[float, str]): Variable length argument list that accepts floats or
strings.
**kwargs (Dict[str, Any]): Arbitrary keyword arguments as a dictionary of string
keys and values of any type.
Returns:
Tuple[bool, List[str]]: A tuple containing:
- bool: Always True for this example.
- List[str]: A list with a single string describing the received arguments.
"""
result = (
f"Received: param1={param1}, param2={param2}, optional_param={optional_param}, "
f"args={args}, kwargs={kwargs}"
)
No Linebreaks In Summary Line
The summary line cannot contain line breaks and must not exceed the maximum line length. Ensure that the summary line provides a brief description of the function’s purpose. Further explanation and details can be given in the Description text block underneath.
3.2. Description#
The description should be detailed and may contain various rich information elements such as mathematical expressions, external references, URLs, admonitions, etc.
Code:
"""
This function calculates the energy using the formula :math:`E = mc^2`.
You can also declare the math expression as:
.. math::
E = mc^2
"""
Result
This function calculates the energy using the formula \(E = mc^2\):
You can also declare the math expression as:
The docstring setup supports some special cases of external references:
Code:
"""
For more details, refer to the publication DOI: :doi:`10.31235/osf.io/dx87u`.
This issue is tracked under :gh-issue:`156`.
Contributed by :gh-user:`octocat`.
"""
Result
For more details, refer to the publication DOI: doi:10.31235/osf.io/dx87u.
This issue is tracked under Issue #156.
Contributed by @octocat.
Include URLs directly in the description
Code:
"""
Visit the `MedModels <https://medmodels.de>`_ for more information.
"""
Result
Visit MedModels for more information.
You can add admonitions for important information. For more details check out the official docs.
Code:
"""
.. attention::
attention!
.. caution::
caution!
.. danger::
danger!
.. error::
error!
.. hint::
hint!
.. important::
important!
.. note::
note!
.. tip::
tip!
.. warning::
warning!
"""
Result
Attention
attention!
Caution
caution!
Danger
danger!
Error
error!
Hint
hint!
Important
important!
Note
note!
Tip
tip!
Warning
warning!
Other reST Elements:
You can also use various other reST elements to enrich the documentation:
Lists: For bullet points or numbered lists.
Code Blocks: For including code snippets.
Tables: For tabular data.
Refer to the Sphinx & RST Cheat Sheet for more examples and details.
3.3. Arguments#
Document parameters under the Args section. Each parameter should include its name, type, and a brief description.
Example:
"""Example module with docstrings for the developer guide."""
from __future__ import annotations
from typing import Any, Dict, Iterator, List, Optional, Tuple, Union
def example_function_args(
param1: int,
param2: Union[str, int],
optional_param: Optional[List[str]] = None,
*args: Union[float, str],
**kwargs: Dict[str, Any],
) -> Tuple[bool, List[str]]:
"""Example function with PEP 484 type annotations and PEP 563 future annotations.
This function shows how to define and document typing for different kinds of
arguments, including positional, optional, variable-length args, and keyword args.
Args:
param1 (int): A required integer parameter.
param2 (Union[str, int]): A parameter that can be either a string or an integer.
optional_param (Optional[List[str]], optional): An optional parameter that
accepts a list of strings. Defaults to None if not provided.
*args (Union[float, str]): Variable length argument list that accepts floats or
strings.
**kwargs (Dict[str, Any]): Arbitrary keyword arguments as a dictionary of string
keys and values of any type.
Returns:
Tuple[bool, List[str]]: A tuple containing:
- bool: Always True for this example.
- List[str]: A list with a single string describing the received arguments.
"""
result = (
f"Received: param1={param1}, param2={param2}, optional_param={optional_param}, "
f"args={args}, kwargs={kwargs}"
)
No Linebreak in Type Definitions
When writing type definitions in argument docstrings, avoid placing line breaks inside the type annotations. For instance, complex types like (Union[str, List[str], Dict[str, Any]]) should appear on a single line without splitting across lines. This ensures the type definition remains clear and avoids parsing issues.
If a type definition exceeds the maximum line length limit, deactivate the line length rule for that doctstring using # noqa: W505 after the closing """. This keeps the type annotation intact while preventing the linter from flagging the long line as an error.
No Boolean Argument Types
Avoid using booleans as function arguments due to the “boolean trap”. Booleans reduce code clarity, as True or False doesn’t explain meaning. They also limit future flexibility — if more than two options are needed, changing the argument type can cause breaking changes. Instead, use an enum or a more descriptive type for better clarity and flexibility.
For more information, you can refer to Adam Johnson’s article which discusses this in detail and provides examples of how to avoid the boolean trap.
3.4. Return Types#
Document return types under the Returns section. Each return type should include the type and a brief description.
Example:
def example_function(param1, param2):
"""This function performs an example operation.
Returns:
bool: True if successful, False otherwise.
"""
Don’t Document None Return Value
Don’t add a Returns section when the function has no return value (def fun() -> None)
3.5. Examples#
Provide examples under the Examples section by using Sphinx’s .. code-block:: directive within the docstrings.
You need to decalare two .. code-block sections per example. The first one to shows the executed python code. The second one shows the output.
Execute block
The first code block needs to start as shown below. It sets the code highlighting to python and activates line numbers with :linenos:.
.. code-block:: python
:linenos:
<python code>
Result block
The second block shows the return value when executing the code. The output value(s) should be entered after >>>.
.. code-block:: python
>>> Output
Full Example:
def example_function(param1, param2):
"""This function performs an example operation.
Examples:
1. Example
.. code-block:: python
:linenos:
example_function(
arg0=1,
arg1="A"
)
.. code-block:: python
>>> True
"""
Will be shown in the API Docs as:
Examples
Example:
1example_function(
2 arg0=1,
3 arg1="A"
4)
>>> True
Check out the docs of find_reference_edge() for a real example.
3.6. Raises#
Document any exceptions that the function or class might raise under the Raises section.
Example:
def example_function(param1, param2):
"""This function performs an example operation.
Raises:
ValueError: If `param1` is not an integer.
"""