Conformity Sphinx Extensions

With Conformity, your class definitions are more meaningful and powerful. So, too, should be your auto-generated documentation for those classes. Conformity includes Sphinx extensions to help you achieve the most-effective documentation possible.

Installation

Installing Conformity normally already includes the Sphinx extensions, but that does not mean they can automatically be used. Unlike proper Conformity, Conformity’s Sphinx extensions have less-lenient dependencies. You must be running at least Python 3.6 and at least Sphinx 2.2. Once you meet these criteria, you can install Conformity normally as a part of your documentation dependency installation.

To use the Conformity extension for Sphinx’s Autodoc, you’ll need to have at least these two extensions configured in your documentation conf.py file:

extensions = [
    ...
    'sphinx.ext.autodoc',
    ...
    'conformity.sphinx_ext.autodoc',
    ...
]

To use the Conformity extension for Sphinx’s Linkcode, you do not have to configure that extension, but you do need to configure the standard Linkcode extension:

extensions = [
    ...
    'sphinx.ext.linkcode',
    ...
]

What do the Extensions Do?

Conformity’s Sphinx Autodoc extension hooks in to registered Autodoc events to intercept Autodoc documentation and modify it before it gets rendered. It looks for and does the following things:

  • If a class being documented uses Attrs and the attr.ib fields have comment-based Python Type Annotations, the extension parses and resolves those type annotations and adds them to the documentation. It does not need to do anything with Python 3.6+ syntax-based Type Annotations, because Autodoc already handles those.

  • If a method being documented uses comment-based Python Type Annotations for arguments or return type, the extension parses and resolves those type annotations and adds them to the documentation. It does not need to do anything with Python 3.6+ syntax-based Type Annotations, because Autodoc already handles those.

  • If a class being documented extends Settings (see Conformity Settings), the extension parses the schema and contents and appends documentation to the class docstring detailing the schema requirements and the default values.

  • If a class being documented is decorated with @fields.ClassConfigurationSchema (see Class Configuration Schemas), the extension parses the schema and appends documentation to the class docstring detailing the schema requirements for the constructor arguments.

  • If your module has an attribute that is an instance of any Conformity field and that attribute has a docstring directly below it (even an empty one), the extension parses the schema of that field and appends its documentation to the docstring for that attribute.

The Linkcode extension does not have an events to hook in to like the Autodoc extension. Instead, it just provides a helper method that you can use to fulfill Linkcode’s linkcode_resolve attribute in conf.py. Writing a linkcode_resolve function for your project often involves a lot of boilerplate code. To solve this, Conformity’s extension provides a create_linkcode_resolve function that takes several arguments and creates a function for you. Currently, it supports only GitHub projects. To use this extension, add this to your conf.py:

from conformity.sphinx_ext.linkcode import create_linkcode_resolve

...

linkcode_resolve = create_linkcode_resolve(
    'my_github_user',
    'my_project_name',
    'my_base_module',
    my_project_version_tag_string,
)

For example, if your GitHub the main Python module for your project is located at https://github.com/my_user/cool_project/project_module/__init__.py and you have imported __version__, which holds your project version and corresponds to the name of a tag on GitHub, you would call it like this:

linkcode_resolve = create_linkcode_resolve('my_user', 'cool_project', 'project_module', __version__)

The linkcode_resolve function created will try to link all source code to a blob/ commit hash on GitHub, but if it can’t determine the current Git commit, it will instead use the tree/ version tag as specified in the last argument.

Copyright © 2023 Eventbrite, freely licensed under Apache License, Version 2.0.

Documentation generated 2023 January 10 22:12 UTC.