Metadata-Version: 2.5
Name: irondocs
Version: 0.3.0
Summary: Test codeblocks in pytest
Project-URL: homepage, https://irondocs.dev/python/introduction/
Project-URL: repository, https://github.com/datisthq/irondocs
Author: Evgeny Karev
License-Expression: MIT
License-File: LICENSE.md
Keywords: doctest,irondocs,markdown,pytest,testing
Classifier: Development Status :: 4 - Beta
Classifier: Framework :: Pytest
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Testing
Classifier: Typing :: Typed
Requires-Python: >=3.12
Requires-Dist: pytest>=8.0
Requires-Dist: textlane>=0.5.0
Description-Content-Type: text/markdown

# Irondocs

Run Python code blocks from your markdown docs as real pytest tests. Mark a
fenced block with `test`, and it becomes a runnable assertion — no separate
test file, no boilerplate, no drift between docs and code. Python 3.12+.

## Install

```bash
pip install irondocs
# or
uv add --dev irondocs
```

Irondocs is a pytest plugin: installing it is enough to load it.

## Write a doctest

Add `test` to any `python` fence in any `.md` file. The block runs as one test
named after the nearest preceding heading. Failures read like any pytest
failure, pointing at the line of the `.md` file.

````md
```python test
from statistics import mean

assert mean([1, 2, 3]) == 2
```
````

Untagged `python` blocks render normally and are not run, so you can mix
illustrative snippets and runnable assertions in the same article.

## Wire it into pytest

List the markdown files to collect under `irondocs_files`, and make sure pytest
walks the folder that holds them:

```toml title="pyproject.toml"
[tool.pytest.ini_options]
testpaths = ["tests", "docs"]
irondocs_files = ["docs/*.md"]
```

Run your usual `pytest` — your `.md` files now run alongside your `test_*.py`
files. See [Writing tests](https://irondocs.dev/python/writing-tests/) for the marker syntax,
[Running tests](https://irondocs.dev/python/running-tests/) for what to expect at the terminal, and
[Configuration](https://irondocs.dev/python/configuration/) for the options.
