mktestdocs

By default, check_md_file assumes each code block in a markdown file is independent. If your code blocks are sequential (e.g., the second block relies on variables defined in the first), you must set memory=True to maintain state between blocks.

import pathlib
from mktestdocs import check_md_file

fpath = pathlib.Path("docs") / "multiple-code-blocks.md"

# Use memory=True to allow blocks to depend on each other
check_md_file(fpath=fpath, memory=True)

Install the package using pip to enable running pytest against markdown files and docstrings.

pip install mktestdocs

The mktestdocs package provides utilities for validating markdown files, inspecting code blocks, and checking docstrings within a codebase. The primary entrypoints for testing and inspection are exported via the package root.

from mktestdocs import (
    check_codeblock,
    check_docstring,
    check_md_file,
    grab_code_blocks,
    get_codeblock_members,
    register_executor
)

Use check_md_file to validate code blocks within a markdown file. By default, it looks for blocks tagged with python and executes them. This is useful for ensuring that documentation examples and assert statements remain valid.

import pathlib
import pytest
from mktestdocs import check_md_file

@pytest.mark.parametrize('fpath', pathlib.Path("docs").glob("**/*.md"), ids=str)
def test_files_good(fpath):
    check_md_file(fpath=fpath)

Bash code blocks are supported by default. You can test them by specifying the language in check_md_file.

import pathlib
from mktestdocs import check_md_file

fpath = pathlib.Path("docs") / "bash-support.md"

check_md_file(fpath=fpath, lang="python")
check_md_file(fpath=fpath, lang="bash")

Use check_docstring to validate markdown content found within Python object docstrings. This is particularly useful when using tools like mkdocstrings to generate documentation from docstrings.

import pytest
from mktestdocs import check_docstring
from dinosaur import roar, super_roar

@pytest.mark.parametrize('func', [roar, super_roar], ids=lambda d: d.__name__)
def test_docstring(func):
    check_docstring(obj=func)

You can extend mktestdocs to support other languages (like json) by using register_executor. This function takes a language tag and a callback function that receives the code block text. The callback should perform the validation (e.g., parsing or asserting).

import json
import pathlib
from mktestdocs import check_md_file, register_executor

def parse_json(json_text):
    json.loads(json_text)

# Register 'json' as a supported language
register_executor("json", parse_json)

# Test the markdown file using the new 'json' executor
check_md_file(fpath=pathlib.Path("docs") / "additional-language-support.md", lang="json")

The get_codeblock_members utility allows you to automatically find all methods or properties within a class that contain docstrings, which can then be passed to check_docstring for batch testing.

import pytest
from mktestdocs import check_docstring, get_codeblock_members
from dinosaur import Dinosaur

# Retrieves all methods/properties that have a docstring.
members = get_codeblock_members(Dinosaur)

@pytest.mark.parametrize("obj", members, ids=lambda d: d.__qualname__)
def test_member(obj):
    check_docstring(obj)

The package provides tools to extract and validate code blocks within documentation:

• grab_code_blocks: Extracts code blocks from a source.
• check_codeblock: Validates a specific code block.
• get_codeblock_members: Retrieves members associated with code blocks.