Doctests#

Introduction#

To ensure that the examples in docstrings remain correct and up to date, we use pytest’s built-in support for doctest. Every Examples section must be written in valid Python syntax using the >>> prompt, so it can be automatically tested.

Testing Examples with pytest#

How to run doctests#

You can run the doctests across the entire codebase using:

pytest --doctest-modules

This command will:

  • Recursively search for Python files.

  • Extract any lines starting with >>> in docstrings.

  • Execute them and compare the output with the expected results.

Tips#

  • Make sure your example is minimal but functional.

  • Avoid depending on random data or external files unless mock data is provided.

  • Prefer the real demo systems from molsysviewer.demo when you need a molecular system.

  • If MolSysMT/numba is involved, set NUMBA_CACHE_DIR=/tmp/numba_cache in your session to avoid cache issues.

Example of a testable docstring#

def add(a, b):
    """
    Adding two numbers.

    Parameters
    ----------
    a : int
    b : int

    Returns
    -------
    int

    Examples
    --------
    >>> add(2, 3)
    5
    """
    return a + b

Adding well-formed and tested examples helps users understand usage and prevents regressions in the future. This is how we test this example embeded in the docstring:

pytest --doctest-modules molsysviewer