Projects normally have examples in the examples/ directory and in docstring documentation. The ones in examples/ are currently being linted, but never ran. The ones in docstrings are never linted nor ran. All of this very subject to break when there are updates.

In docstrings there are mainly 2 types of examples in documentation:

• doctest: Usually any block starting with >>> in a docstring
• Markdown examples. Could be in:
  • docstrings (Python files)
  • Other high-level documentation in docs/.

We mainly use markdown examples, so we should focus on that first.

There are several tools to actually test those examples to make sure they work, so we should use one:

• https://docs.python.org/3/library/doctest.html

• https://docs.pytest.org/en/7.1.x/how-to/doctest.html

• https://stackoverflow.com/questions/23250068/python-doctest-my-github-markdown-files

  • https://pypi.org/project/phmdoctest/ (+)
  • https://github.com/ryneeverett/mkcodes (-)