Sphinx documentation of python script with pytest marker

Question

I have been looking at using Sphinx to document test modules that uses pytest. In the script there are user defined pytest.mark. Is there a way to configure Sphinx or the .rst template file to include the pytest.mark definitions even though they are outside of the docstring?

The sphinx documentation on the use of :regexp: is extremely vague and I have been unable to find a good example that uses it.

Python 2.7.6 Sphinx-build 1.3.3

"""
    script: test_sample.py
    :Test Description: Simple test to show function of py.test and sphinx doc
    :Author: James Brown
    Requirement ID: Test1234
"""
import sys
from sys import argv
import re
import pytest


pytestmark = [
    pytest.mark.author("jbrown"),
    pytest.mark.req("test-001"),
    pytest.mark.testtype("Full"),
    pytest.mark.mat0]

blah = """
    blah
    blah
    blah
"""


def func(x):
    """
        Returns an integer incremented by one
    """

    return x + 1

def test_answer():
    """
        Checks if value equals 5
    """
    assert func(3) == 5

rst file addition

.. exec::
    import re
    from src.test_samplepytest import pytestmark

    attre = re.compile(r"\'(\w+)\'.*\(\'?(\w*)")

    for value in pytestmark:
        mark = str(value)
        att = attre.search(mark)
        if att.group(2):
            print "{:<10}: {:<15}\n".format(att.group(1),att.group(2))
        else:
            print "{:<10}: \n".format(att.group(1))'

[JSON Dictionary](http://stackoverflow.com/questions/27875455/displaying-dictionary-data-in-sphinx-documentation) gets me really close. The dictionary is being pulled over, but it is not a JSON dictionary? `Error: Unable to execute python code at src.rst:23: is not JSON serializable` — Eric Evans, Jan 11 '16 at 16:22
The EXEC directive in the sphinx conf.py file works. It would be nice to understand how to put this into a directive so that the .rst files did not look so nasty. Reference [Directive](http://stackoverflow.com/questions/7250659/python-code-to-generate-part-of-sphinx-documentation-is-it-possible/18143318#18143318) — Eric Evans, Jan 13 '16 at 20:30
Yes, I chose to capture the pytest.mark details in a database. I then execute a query in the sphinx rst file that returns a formatted table. — Eric Evans, Dec 13 '17 at 17:52

score 2 · Accepted Answer · answered Dec 13 '17 at 18:08

I chose to write a file parser for the test script. This runs validation, pylint, etc. and loads the interesting information into a database table.

Then I can query the database, returning a formatted table using https://pypi.python.org/pypi/tabulate.

The sphinx rst file contains:

  5     .. exec::                                                                  
  6         dbquery('col1,col2,col3','test_moduleName',db='my_database')

Sphinx documentation of python script with pytest marker

1 Answers1