better-apidoc

A version of sphinx-apidoc with support for templating

Author: Michael Goerz <[email protected]>

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. After a lengthy gestation period, it is on track to be merged back into apidoc.py: https://github.com/sphinx-doc/sphinx/pull/6768

Note: Due to changes in Sphinx 1.8, better-apdic in its current form can no longer run as a script from the command line, and must be run from inside conf.py, see "Usage" below.

Fundamentally, better-apidoc 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

Due to changes in Sphinx 1.8, better_apidoc can no longer be run as an independent script. Instead, it must be set up in Sphinx's conf.py. In conf.py, define a function like this:

def run_apidoc(app):
    """Generage API documentation"""
    import better_apidoc
    better_apidoc.APP = app
    better_apidoc.main([
        'better-apidoc',
        '-t',
        os.path.join('.', '_templates'),
        '--force',
        '--no-toc',
        '--separate',
        '-o',
        os.path.join('.', 'API'),
        os.path.join('..', 'src', 'krotov'),
    ])

You will have to adjust the last two lines: os.path.join('.', 'API') is the location relative to conf.py where the API rst files should be generated. In the last line, os.path.join('..', 'src', 'krotov') is the location of the package code (I strongly advocate the use of a src directory).

Then, at the end of conf.py, add the following code:

def setup(app):
    app.connect('builder-inited', run_apidoc)

For an full example, see the conf.py file of the krotov 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

v0.3.0 (2019-04-02): Adapt to changes in Sphinx 1.8 (#14). As a result, sphinx-apidoc can no longer run as a standalone script, but must be called from inside conf.py.

v0.3.1 (2019-04-04): Fix calls to Sphinx's get_documenter function to work for any version of version of Sphinx (tested on 1.6-2.0)

v0.3.2 (2021-05-10): Compatibility update for Sphinx 4.0 (#17)

License

This software is available under the terms of the BSD license. See LICENSE for details.