https://github.com/goerz/better-apidoc
A version of sphinx-apidoc with support for templating
https://github.com/goerz/better-apidoc
apidoc documentation-generator python sphinx sphinx-doc
Last synced: 4 months ago
JSON representation
A version of sphinx-apidoc with support for templating
- Host: GitHub
- URL: https://github.com/goerz/better-apidoc
- Owner: goerz
- License: bsd-2-clause
- Created: 2017-03-08T04:40:47.000Z (over 8 years ago)
- Default Branch: master
- Last Pushed: 2021-05-10T20:27:52.000Z (about 4 years ago)
- Last Synced: 2025-02-27T12:20:48.465Z (4 months ago)
- Topics: apidoc, documentation-generator, python, sphinx, sphinx-doc
- Language: Python
- Size: 49.8 KB
- Stars: 32
- Watchers: 3
- Forks: 6
- Open Issues: 4
-
Metadata Files:
- Readme: README.markdown
- License: LICENSE
Awesome Lists containing this project
README
# better-apidoc #
[](https://badge.fury.io/py/better-apidoc)
A version of [sphinx-apidoc][] with support for templating
Author: Michael Goerz <>
Website: [Github][]
[Github]: https://github.com/goerz/better-apidoc#better-apidoc
[sphinx-apidoc]: http://www.sphinx-doc.org/en/stable/man/sphinx-apidoc.html
## Installation ##
pip install better-apidoc
This will install `better-apidoc` in the current environment's `bin` folder.
[virtualenv]: http://docs.python-guide.org/en/latest/dev/virtualenvs/
[pipsi]: https://github.com/mitsuhiko/pipsi#pipsi
[conda env]: http://conda.pydata.org/docs/using/envs.html
## 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 `` only contains
modules. Note that if `` 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](https://github.com/mabuchilab/QNET/blob/develop/docs/_templates/package.rst)
and
[module.rst](https://github.com/mabuchilab/QNET/blob/develop/docs/_templates/module.rst)
for an example template. These render to e.g.
[apidoc.py]: https://github.com/sphinx-doc/sphinx/blob/master/sphinx/apidoc.py
[Jinja]: http://jinja.pocoo.org
[`__imported_data__`]: https://github.com/mabuchilab/QNET/blob/4e637b18c53cbee598ed58c3b7f7820dd54216db/qnet/algebra/__init__.py#L56
[Sphinx issue #3545]: https://github.com/sphinx-doc/sphinx/issues/3545
[Stackoverflow]: http://stackoverflow.com/questions/29385564/customize-templates-for-sphinx-apidoc
## Usage ##
Due to [changes in Sphinx 1.8][issue14], `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][srcdir]).
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][krotovconf]
[krotovconf]: https://github.com/qucontrol/krotov/blob/master/docs/conf.py
[srcdir]: https://blog.ionelmc.ro/2014/05/25/python-packaging/#the-structure
## 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][issue14]). 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][issue17])
[issue14]: https://github.com/goerz/better-apidoc/issues/14
[issue17]: https://github.com/goerz/better-apidoc/issues/17
## License ##
This software is available under the terms of the BSD license. See [LICENSE]
for details.
[LICENSE]: LICENSE