Metadata-Version: 2.1
Name: pytest-doctest-mkdocstrings
Version: 0.1.1
Summary: Run pytest --doctest-modules with markdown docstrings in code blocks (```)
Author: Mike Foster
Project-URL: Homepage, https://github.com/MusicalNinjaDad/pytest-doctest-mkdocstrings
Project-URL: Documentation, https://github.com/MusicalNinjaDad/pytest-doctest-mkdocstrings
Project-URL: Repository, https://github.com/MusicalNinjaDad/pytest-doctest-mkdocstrings
Project-URL: Issues, https://github.com/MusicalNinjaDad/pytest-doctest-mkdocstrings/issues
Project-URL: Changelog, https://github.com/MusicalNinjaDad/pytest-doctest-mkdocstrings/blob/main/CHANGELOG.md
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Framework :: Pytest
Classifier: Intended Audience :: Developers
Classifier: Natural Language :: English
Requires-Python: >=3.7
Description-Content-Type: text/markdown
Requires-Dist: pytest
Provides-Extra: dev
Requires-Dist: mkdocs ; extra == 'dev'
Requires-Dist: mkdocstrings[python] ; extra == 'dev'
Requires-Dist: mkdocs-material ; extra == 'dev'
Requires-Dist: ruff ; extra == 'dev'

# pytest-doctest-mkdocstrings

A pytest plugin that allows you to use doctest and enclose your example code blocks in ` ``` ` codeblocks (e.g. when building documentation with mkdocs and mkdocstring).

> **v0.1.0 - Breaking change** - you now need to specifically add the command line option `--doctest-mdcodeblocks` when calling pytest

Usually this docstring would fail doctest:

```
    """
    A function description

    Examples:
    --------
    ```
    >>> x = 1
    >>> x
    1
    ```
    """
```

As doctest looks for the output
```
Expected:
    1
    ```
Got:
    1
```

This plugin works by mockeypatching doctests parser when pytest begins each test session and including ` ``` ` as an identifier of the end of an expected result (a `want`).

It only works when doctest is invoked via pytest, not when invoking doctest directly.

If you have code examples or expected results which actually contain ` ``` ` then you'll need to re-write them.

## Usage

> **TL;DR**: invoke pytest with `--doctest-mdcodeblocks`

1. **Strongly recommended** to set up a virtual environment first! (e.g.. `python3 -m venv .venv`, `. .venv/bin/activate`)
1. Install with `pip install pytest-doctest-mkdocstrings`
1. Run pytest: `pytest --doctest-mdcodeblocks --doctest-modules --doctest-glob="*.md"`

You can also add the following to your `pyproject.toml` so that pytest always runs doctests:
```
[tool.pytest.ini_options]
addopts = [
    "--doctest-modules",
    "--doctest-glob='*.md'",
    "--doctest-mdcodeblocks"
]
```

To temporarily override the setting use: `pytest --no-doctest-mdcodeblocks`
