A version of sphinx-apidoc with support for templating
Author: Michael Goerz <[email protected]>
Website: Github
pip install better-apidoc
This will install better-apidoc
in the current environment's bin
folder.
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: sphinx-doc/sphinx#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
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
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 thein_list
argument ofget_members
. - add capability to generate autosummary-like tables, via
out_format='table'
inget_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)
This software is available under the terms of the BSD license. See LICENSE for details.