mktestdocs.

Examples in your documentation should always run. If there's errors in it, people who are trying to learn your tool will have a bad time. To prevent errors from getting in the way, we wrote a small library to help you out.

Introducing: mktestdocs! It's a tool that can take python snippets from markdown files and treat them as unit tests for pytest.

Take the following code snippet.

from sklearn.linear_modle import LogisticRegression

lr = LogisticRegression()

It's hard to spot, but there's a typo! The linear_modle submodule does not exist, it should have been linear_model.

You can use mktestdocs inside of a standard test file to generate unit tests from markdown files. A common pattern is shown below.

import pathlib
import pytest

from mktestdocs import check_md_file

doc_paths = pathlib.Path("docs").glob("**/*.md")

# Note the use of `ids` as it makes for pretty output
@pytest.mark.parametrize('fpath', doc_paths, ids=str)
def test_files_good(fpath):
    check_md_file(fpath=fpath, memory=True)

The check_md_file can be run to take all the python snippets in the file and treat it as a single file (memory=True) or it can run each code snippet as an independant cell (memory=False).

It's a small package without a lot of functions, but we hope you find it useful as a simple checking mechanism for your documentation (or at the very least: the readme.md file). There's also some niche tools that allow you to test python snippets in docstrings if you use markdown there. If you want to learn more, definately check out the project page.