Documenting XC exceptions

XC contains a Sphinx extension called rjgtoys.xc.autodoc that will generate documentation for your XC exceptions.

This extension builds on the sphinx.ext.autodoc extension, and extends the autoexception directive so that it generates more detailed documentation for XC exceptions than for others.

Installation

rjgtoys.xc.autodoc depends on the sphinx_autodoc_typehints extension, which must be installed in order for for it to work:

pip install sphinx-autodoc-typehints

Enable the rjgtoys.xc.autodoc extension

Add rjgtoys.xc.autodoc to the extensions listed in your conf.py Sphinx configuration. For example, add the following:

extensions.extend([
    'rjgtoys.xc.autodoc'
])

There is no need to list either sphinx.ext.autodoc or sphinx_autodoc_typehints; both are required, and will be enabled automatically by rjgtoys.xc.autodoc.

Example markup and output

The example module examples/insuffspace.py (included in the XC source code) declares the following exception:

class InsufficientSpace(Error):
    """Raised when a filesystem has insufficient space."""

    detail = "Filesystem {path} has only {avail} bytes free, need {need}"

    path: str = Title("The filesystem mount point")
    avail: int = Field(..., title="Number of bytes free on the filesystem")
    need:  int = Title("Number of bytes needed")

To document that, include an autoexception directive in your Sphinx markup:

.. autoexception:: examples.insuffspace.InsufficientSpace

The result is as follows:

exception InsufficientSpace(path, avail, need)[source]

Raised when a filesystem has insufficient space.

A subclass of rjgtoys.xc.Error

Parameters

  • path (str) – The filesystem mount point

  • avail (int) – Number of bytes free on the filesystem

  • need (int) – Number of bytes needed

Each parameter defines an attribute of the same name.

Properties (read-only)

typename = ‘examples.insuffspace.InsufficientSpace’

title = ‘Raised when a filesystem has insufficient space.’

detail = ‘Filesystem {path} has only {avail} bytes free, need {need}’

status = 400

For more information about the above properties please refer to the documentation for rjgtoys.xc.

Compare the plain autoexception output:

exception InsufficientSpace(**kwargs)[source]

Raised when a filesystem has insufficient space.