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
Take the following code snippet.
from sklearn.linear_modle import LogisticRegression lr = LogisticRegression()
It's hard to spot, but there's a typo! The
does not exist, it should have been
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)
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 (
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.
Back to labs main.