Testing Python examples in the documentation

Testing Python examples in the documentation#

We can use the Python doctest module for testing examples in the documentation. Run it with

python -m doctest <filename>

on your markdown file.

See documentation contributions for how to write your examples such that they can be tested with doctest.

For instance, assume that you have the following example in your documentation

```python
    >>> 1 + 1  # doctest: +SKIP
    3

```

python -m doctest documentation_testing.md would print the following message:

**********************************************************************
File "documentation_testing.md", line 15, in documentation_testing.md
Failed example:
    1 + 1
Expected:
    3
Got:
    2
**********************************************************************

Now you copy the output following Got:, including the 4 indentation spaces, into your example.

Note that the comment #doctest: +SKIP was added to the above example in order to not trigger a doctest failure when validating the markdown file containing this guideline.

Building Python API documentation#

The Python API reference is generated by Sphinx using AutoAPI. The entry points in the docs are:

  • Python API <autoapi/index> in doc/api.rst

  • Python API <autoapi/index> in doc/index.rst

Build steps from the repository root:

python -m pip install -r requirements_doc.txt
cmake -S . -B build -DWITH_DOC=ON
cmake --build build --target Sphinx

Expected output location:

  • HTML root: build/doc/html/index.html

  • Python API index: build/doc/html/autoapi/index.html

If autoapi.extension cannot be imported, install or re-install the docs dependencies from requirements_doc.txt.

If Python API pages are missing, ensure that the CMake configuration used to build docs has access to either:

  • built Python bindings under the active build directory, or

  • source Python modules under bindings/python and python/dlite-python.

Contents