better-apidoc

A version of sphinx-apidoc with support for templating

Author: Michael Goerz <goerz@stanford.edu>

Website: Github

Installation

pip install better-apidoc

This will install better-apidoc in the current environment's bin folder.

Templating

The better-apidoc script is a patched version of Sphinx' apidoc.py. If well-received, I may try to have this patch merged back into Sphinx as an update to sphinx-apidoc.

It adds the -t/--templates option to the script. If this option is not given, it is identical to sphinx-apidoc. With the option, Jinja-based templates are used for the generated ReST files. The template directory given via -t must contain the template files module.rst and package.rst.

The following variables are available in the templates:

name: the name of the module/package
fullname: the name of the module/package, including package path (dot-separated)
members: list of names of all the members defined directly in the module/package
functions: list all the functions in members
classes: list of all the classes in members
exceptions: list of all the exceptions in members
data: list of all the data items in members
subpackages: For packages, list of subpackage names. Empty list for modules
submodules: For packages, list of submodule names. Empty list of modules

Furthermore, the function get_members is made available to the template:

def get_members(
        typ=None, include_imported=False, out_format='names',
        in_list=None, includeprivate=opts.includeprivate, known_refs=None):
    """Return a list of members of the current module

    Args:
        typ (None or str): One of None, 'function', 'class', 'exception',
            'data'. If not None, only members of the corresponding type
             will be returned
        include_imported (bool): If True, include members that are imported
            from other modules. If False, only return members that are
            defined directly in the module.
        out_format (str): One of 'names', 'fullnames', 'refs', and 'table'
        in_list (None or str): If not None, name of a module
            attribute (e.g. '__all__'). Only members whose names appears in
            the list will be returned.
        includeprivate (bool): If True, include members whose names starts
            with an underscore
        know_refs (None or dict or str): If not None, a mapping of names to
            rull rst-formatted references. If given as a str, the mapping
            will be taken from the module attribute of the given name. This
            is used only in conjunction with ``out_format=refs``, to
            override automatically detected reference location, or to
            provide references for object that cannot be located
            automatically (data objects).

    Returns:
        list: List of strings, depending on `out_format`.

        If 'names' (default), return a list of the simple names of all
        members.

        If 'fullnames', return a list of the fully qualified names
        of the members.

        If 'refs', return a list of rst-formatted links.

        If 'table', return a list of lines for a rst table similar to that
        generated by the autosummary plugin (left column is linked member
        names, right column is first sentence of the docstring)


    Note:
        For data members, it is not always possible to determine whther
        they are imported or defined locally. In this case, `in_list` and
        `known_refs` may be used to achieve the desired result.

        If using ``in_list='__all__'`` for a package you may also have to
        use ``include_imported=True`` to get the full list (as packages
        typically export members imported from their sub-modules)
    """

You can use this in a template as e.g.

{% set all_refs = get_members(in_list='__all__', include_imported=True, out_format='refs') %}
{% if all_refs %}
    ``__all__``: {{ all_refs|join(", ") }}
{%- endif %}

to get a linked list of members in the __all__ list of a module. Note that the template variables members, functions, classes, exceptions, and data all could be obtained by using get_members as well; they are provided as variables for convenience only.

The package.rst template will be used when rendering any package. The module.rst template will be used when rendering modules if the -s/--separate option is given, or if the <module_path> only contains modules. Note that if <module_path> contains a package and the -s/--separate is not given, the module.rst template will not be used.

The addition of templates to apidoc addresses Sphinx issue #3545. That is, it is now possible to have a list of members with short summaries at the top of the API documentation that links to the more detailed information below. It is also directly addresses the demand for this feature expressed on Stackoverflow.

See package.rst and module.rst for an example template. These render to e.g. https://qnet.readthedocs.io/en/latest/API/qnet.algebra.core.operator_algebra.html

Usage

See better-apidoc -h

You can also use this as a module better_apidoc, e.g. from the Sphinx conf.py file to automate the generation of API files. For an example, see the conf.py file of the QNET project

History

v0.1.0 (2017-03-08): first public release

v0.1.1 (2017-03-12): handle custom autodocumenters

v0.1.2 (2017-03-12): support for (non-standard) __local_data__ and __imported_data__ class attributes to properly identify data members

v0.1.3 (2018-03-14): support Sphinx 1.7

v0.1.4 (2018-03-24): support both Sphinx 1.6 and 1.7

v0.2.0 (2018-07-01):

make function get_members available to templates
remove template variables member_imports, members_imports_refs, all_refs: their functionality is now achieved with get_members
remove use of non-standard __local_data__ and __imported_data__ module attributes. These can still be used via the in_list argument of get_members.
add capability to generate autosummary-like tables, via out_format='table' in get_members (but solving autosummary's problem of not generating links for imported members)
This release breaks templates written for v0.1.x

License