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
# 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:
- reStrcutured text
Why not sphinx?
(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
$ pip install pytest-docs
--docs [PATH] to create the documentation.
--doc-type to select the type (currently supports
@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.
What's planned ahead
- 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.