Skip to main content

Documentation tool for pytest

Project description

A pytest plugin that generates documentation of the testing application itself.

PyPI version Python versions Travis CI Black


Create documentation of your tests. Turns this:

'''This is the module doc'''
import pytest

pytestmark = [
    pytest.mark.pytest_doc(name="Test Docs"),

@pytest.mark.pytest_doc(name="Test Class")
class TestClass:
    '''This is the class doc'''

    def test_func_a(self):
        '''This is the doc for test_func_a'''
        assert 1

    def test_func_b(self):
        '''This is the doc for test_func_b'''
        assert 1

To this:

# Test Docs
This is the module doc

- module_mark
- module_mark_2
- pytest_doc  (name=Test Docs)
## Test Class
This is the class doc

- pytest_doc  (name=Test Class)
- class_marker
### test_func_a
This is the doc for test_func_a

- func_mark_a (foo)
### test_func_b
This is the doc for test_func_b

- kwarg_mark  (goo=bla)

Current supported formats:

  • Markdown

  • 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


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.

What’s planned ahead

  1. See if anyone is even interested in this

  2. Document fixtures

  3. Document tests and fixtures parametrization

  4. 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.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

pytest-docs-0.1.0.tar.gz (7.1 kB view hashes)

Uploaded Source

Built Distribution

pytest_docs-0.1.0-py3-none-any.whl (8.6 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page