exdoc module

This module can be used to automatically generate exceptions documentation marked up in reStructuredText with help from cog and the pexdoc.exh module.

The exceptions to auto-document need to be defined with either the pexdoc.exh.ExHandle.addex() function, the pexdoc.exh.ExHandle.addai() function or via contracts of the pexdoc.pcontracts module, and “traced” before the documentation is generated. In general tracing consists of calling the methods, functions and/or class properties so that all the required exceptions are covered (exceptions raised by contracts are automatically traced when the functions with the contracts are used). A convenient way of tracing a module is to simply run its test suite, provided that it covers the exceptions that need to be documented (for maximum speed the unit tests that cover the exceptions may be segregated so that only these tests need to be executed).

For example, it is desired to auto-document the exceptions of a module my_module.py, which has tests in test_my_module.py. Then a tracing module trace_my_module.py can be created to leverage the already written tests:

# trace_my_module_1.py
# Option 1: use already written test bench
from __future__ import print_function
import copy, os, pytest, pexdoc

def trace_module(no_print=True):
    """ Trace my_module exceptions """
    pwd = os.path.dirname(__file__)
    script_name = repr(os.path.join(pwd, 'test_my_module.py'))
    with pexdoc.ExDocCxt() as exdoc_obj:
        if pytest.main('-s -vv -x {0}'.format(script_name)):
            raise RuntimeError(
                'Tracing did not complete successfully'
            )
    if not no_print:
        module_prefix = 'docs.support.my_module.'
        callable_names = ['func', 'MyClass.value']
        for callable_name in callable_names:
            callable_name = module_prefix+callable_name
            print('\nCallable: {0}'.format(callable_name))
            print(exdoc_obj.get_sphinx_doc(callable_name, width=70))
            print('\n')
    return copy.copy(exdoc_obj)

if __name__ == '__main__':
    trace_module(False)

The context manager pexdoc.exdoc.ExDocCxt sets up the tracing environment and returns a pexdoc.exdoc.ExDoc object that can the be used in the documentation string of each callable to extract the exceptions documentation. In this example it is assumed that the tests are written using pytest, but any test framework can be used. Another way to trace the module is to simply call all the functions, methods or class properties that need to be documented. For example:

# trace_my_module_2.py
# Option 2: manually use all callables to document
from __future__ import print_function
import copy, pexdoc, docs.support.my_module

def trace_module(no_print=True):
    """ Trace my_module_original exceptions """
    with pexdoc.ExDocCxt() as exdoc_obj:
        try:
            docs.support.my_module.func('John')
            obj = docs.support.my_module.MyClass()
            obj.value = 5
            obj.value
        except:
            raise RuntimeError(
                'Tracing did not complete successfully'
            )
    if not no_print:
        module_prefix = 'docs.support.my_module.'
        callable_names = ['func', 'MyClass.value']
        for callable_name in callable_names:
            callable_name = module_prefix+callable_name
            print('\nCallable: {0}'.format(callable_name))
            print(exdoc_obj.get_sphinx_doc(callable_name, width=70))
            print('\n')
    return copy.copy(exdoc_obj)

if __name__ == '__main__':
    trace_module(False)

And the actual module my_module code is (before auto-documentation):

# my_module.py
# Exception tracing initialization code
"""
[[[cog
import os, sys
sys.path.append(os.environ['TRACER_DIR'])
import trace_my_module_1
exobj = trace_my_module_1.trace_module(no_print=True)
]]]
[[[end]]]
"""

import pexdoc

def func(name):
    r"""
    Prints your name

    :param   name: Name to print
    :type name: string

    .. [[[cog cog.out(exobj.get_sphinx_autodoc(width=69))]]]
    .. [[[end]]]

    """
    # Raise condition evaluated in same call as exception addition
    pexdoc.addex(
        TypeError, 'Argument `name` is not valid', not isinstance(name, str)
    )
    return 'My name is {0}'.format(name)

class MyClass(object):
    """ Stores a value """
    def __init__(self, value=None):
        self._value = None if not value else value

    def _get_value(self):
        # Raise condition not evaluated in same call as
        # exception additions
        exobj = pexdoc.addex(RuntimeError, 'Attribute `value` not set')
        exobj(not self._value)
        return self._value

    def _set_value(self, value):
        exobj = pexdoc.addex(RuntimeError, 'Argument `value` is not valid')
        exobj(not isinstance(value, int))
        self._value = value

    value = property(_get_value, _set_value)
    r"""
    Sets or returns a value

    :type:  integer
    :rtype: integer or None

    .. [[[cog cog.out(exobj.get_sphinx_autodoc(width=69))]]]
    .. [[[end]]]
    """

A simple shell script can be written to automate the cogging of the my_module.py file:

#!/bin/bash
set -e

finish() {
    export TRACER_DIR=""
    cd ${cpwd}
}
trap finish EXIT

input_file=${1:-my_module.py}
output_file=${2:-my_module.py}
export TRACER_DIR=$(dirname ${input_file})
cog.py -e -x -o ${input_file}.tmp ${input_file} > /dev/null && \
    mv -f ${input_file}.tmp ${input_file}
cog.py -e -o ${input_file}.tmp ${input_file} > /dev/null && \
    mv -f ${input_file}.tmp ${output_file}

After the script is run and the auto-documentation generated, each callable has a reStructuredText marked-up :raises: section:

# my_module_ref.py
# Exception tracing initialization code
"""
[[[cog
import os, sys
sys.path.append(os.environ['TRACER_DIR'])
import trace_my_module_1
exobj = trace_my_module_1.trace_module(no_print=True)
]]]
[[[end]]]
"""

import pexdoc

def func(name):
    r"""
    Prints your name

    :param   name: Name to print
    :type name: string

    .. [[[cog cog.out(exobj.get_sphinx_autodoc(width=69))]]]
    .. Auto-generated exceptions documentation for
    .. docs.support.my_module.func

    :raises: TypeError (Argument \`name\` is not valid)

    .. [[[end]]]

    """
    # Raise condition evaluated in same call as exception addition
    pexdoc.addex(
        TypeError, 'Argument `name` is not valid', not isinstance(name, str)
    )
    return 'My name is {0}'.format(name)

class MyClass(object):
    """ Stores a value """
    def __init__(self, value=None):
        self._value = None if not value else value

    def _get_value(self):
        # Raise condition not evaluated in same call as
        # exception additions
        exobj = pexdoc.addex(RuntimeError, 'Attribute `value` not set')
        exobj(not self._value)
        return self._value

    def _set_value(self, value):
        exobj = pexdoc.addex(RuntimeError, 'Argument `value` is not valid')
        exobj(not isinstance(value, int))
        self._value = value

    value = property(_get_value, _set_value)
    r"""
    Sets or returns a value

    :type:  integer
    :rtype: integer or None

    .. [[[cog cog.out(exobj.get_sphinx_autodoc(width=69))]]]
    .. Auto-generated exceptions documentation for
    .. docs.support.my_module.MyClass.value

    :raises:
     * When assigned

       * RuntimeError (Argument \`value\` is not valid)

     * When retrieved

       * RuntimeError (Attribute \`value\` not set)

    .. [[[end]]]
    """

Warning

Due to the limited introspection capabilities of class properties, only properties defined using the property built-in function can be documented with pexdoc.exdoc.ExDoc.get_sphinx_autodoc(). Properties defined by other methods can still be auto-documented with pexdoc.exdoc.ExDoc.get_sphinx_doc() and explicitly providing the method/function name.

Context managers

Classes