Usage

In your sphinx config file (e.g. docs/conf.py) add

extensions = [
    # ...
    "sphinx_apipages",
]

And make sure to not list sphinx.ext.autodoc and sphinx.ext.autosummary there, as those are automatically added by sphinx_apipages.

For each (sub-)module you would like to generate API documentation, add a file with the name of the module to docs/api-src/ and list the functions/classes to include with autosummary, compare API documentation example with audb.

When building the documentation, sphinx_apipages will copy all files from docs/api-src/ to docs/api/, and generate RST files for each class and function, and store them under docs/api/ as well.

Configuration

The following configurations are possible.

apipages_src_dir

Folder holding the API source files.

Default: "docs/api-src"

apipages_dst_dir

Folder storing the generated RST files from which the API documentation is build.

Default: "docs/api"

apipages_hidden_methods

List of hidden class methods that should be included in class documentations.

Default: ["__call__"]

Custom templates

You can overwrite how functions and classes are documented by providing custom templates. E.g. you can create a file docs/_templates/autosummary/class.rst to specify how classes are rendered. You will need to add templates_path = ["_templates"] to your sphinx config file (e.g. docs/conf.py). Inside the template you can access the apipages_hidden_methods list by hidden_methods.

The default templates for classes is autosummary/class.rst:

{{ objname | escape | underline}}

.. currentmodule:: {{ module }}

.. autoclass:: {{ objname }}

{% block methods %}
{%- for item in (all_methods + attributes)|sort %}
    {%- if not item.startswith('_') or item in hidden_methods %}
        {%- if item in all_methods %}
{{ (item + '()') | escape | underline(line='-') }}
.. automethod:: {{ name }}.{{ item }}
        {%- elif item in attributes %}
{{ item | escape | underline(line='-') }}
.. autoattribute:: {{ name }}.{{ item }}
        {%- endif %}
    {% endif %}
{%- endfor %}
{% endblock %}

The default template for functions is autosummary/function.rst:

{{ (name + '()') | escape | underline}}

.. currentmodule:: {{ module }}

.. auto{{ objtype }}:: {{ fullname }}

The default template otherwise is autosummary/base.rst:

{{ name | escape | underline}}

.. currentmodule:: {{ module }}

.. auto{{ objtype }}:: {{ fullname }}