A pytest plugin that generates documentation of the testing application itself.
Create documentation of your tests. Turns this:
'''This is the module doc'''
import pytest
pytestmark = [
pytest.mark.module_mark,
pytest.mark.module_mark_2,
pytest.mark.pytest_doc(name="Test Docs"),
]
@pytest.mark.class_marker
@pytest.mark.pytest_doc(name="Test Class")
class TestClass:
'''This is the class doc'''
@pytest.mark.func_mark_a("foo")
def test_func_a(self):
'''This is the doc for test_func_a'''
assert 1
@pytest.mark.kwarg_mark(goo="bla")
def test_func_b(self):
'''This is the doc for test_func_b'''
assert 1
To this:
# Test Docs
This is the module doc
**Markers:**
- module_mark
- module_mark_2
- pytest_doc (name=Test Docs)
## Test Class
This is the class doc
**Markers:**
- pytest_doc (name=Test Class)
- class_marker
### test_func_a
This is the doc for test_func_a
**Markers:**
- func_mark_a (foo)
### test_func_b
This is the doc for test_func_b
**Markers:**
- kwarg_mark (goo=bla)
Current supported formats:
- Markdown
- reStrcutured text
(More accurately, why not sphinx-autodoc?) Sphinx is an amazing tool that I use and used in other project. To use its autodoc plugin, it need the documented plugin to be importable by the python interperter. Pytest test collection and invocation uses a completely separate mechanism. If you believe that it somehow possible to use sphinx to create pytest documentation, please do not hesitate to contact me.
- Python 3.4, 3.5, 3.6 or 3.7
- Pytest >= 3.5.0
You can install "pytest-docs" via pip from PyPI:
$ pip install pytest-docs
Use --docs [PATH]
to create the documentation.
Use --doc-type
to select the type (currently supports md
and rst
)
Use @pytest.mark.pytest_doc(name="Test Class")
to override name of element. It'll override name based on the place it is being used (module, class or function).
Note: pytest-docs uses the pytest collection mechanism, so your documentation will be generated according the the usual collection commands used to run the tests.
- See if anyone is even interested in this
- Document fixtures
- Document tests and fixtures parametrization
- Custom formatters via hooks
Contributions are very welcome. Tests can be run with tox, please ensure the coverage at least stays the same before you submit a pull request.
Distributed under the terms of the MIT license, "pytest-docs" is free and open source software
If you encounter any problems, please file an issue along with a detailed description.
This pytest plugin was generated with Cookiecutter along with @hackebrot's cookiecutter-pytest-plugin template.