Configuration

Global

This section describes the configuration options for sphinx-autodoc2, that you can set in the conf.py file.

autodoc2_packages

The packages to analyse. Each item can be a simple string, pointing to the package path, relative to the source directory (in POSIX format), or it can be a dictionary with more fine-grained control (see Package analysis)).

type: list[str | dict]

default: []

autodoc2_output_dir

The root output directory for the documentation, relative to the source directory (in POSIX format).

type: str

default: apidocs

autodoc2_render_plugin

The renderer to use for the documentation. This can be one of rst or md/myst, to use the built-in renderers, or a string pointing to a class that inherits from RendererBase, such as mypackage.mymodule.MyRenderer.

type: str

default: <class 'autodoc2.render.rst_.RstRenderer'>

autodoc2_render_plugin_regexes

A list of (regex, renderer) to use for specific modules

type: list[tuple[str, str]]

default: []

autodoc2_module_all_regexes

Regexes which match fully qualified module names, to specify they should use the __all__ when determining which children to document

type: list[str]

default: []

autodoc2_skip_module_regexes

Regexes which match fully qualified module/package names, to skip them

type: list[str]

default: []

autodoc2_hidden_objects

The default hidden items. Can contain:

• undoc: undocumented objects

• dunder: double-underscore methods, e.g. __str__

• private: single-underscore methods, e.g. _private

• inherited: inherited class methods

type: list[“undoc” | “dunder” | “private” | “inherited”]

default: {'inherited'}

autodoc2_hidden_regexes

Regexes which match against fully qualified names, to mark them as hidden

type: list[str]

default: []

autodoc2_no_index

Do not generate a cross-reference index.

type: bool

default: False

autodoc2_deprecated_module_regexes

Regexes which match against module names, to mark them as deprecated

type: list[str]

default: []

autodoc2_module_summary

Whether to include a per-module summary.

type: bool

default: True

autodoc2_docstring_parser_regexes

Match fully qualified names against regexes to use a specific parser. The parser can be one of ‘rst’, ‘myst’, or the fully qualified name of a custom parser class. The first match is used.

type: list[tuple[str, str]]

default: []

autodoc2_class_docstring

How to handle documenting of classes. If merge, the __init__ docstring is appended to the class docstring and the __init__ method is omitted.If both, then the __init__ method is included separately.

type: “merge” | “both”

default: merge

autodoc2_class_inheritance

Whether to document class inheritance.

type: bool

default: True

autodoc2_annotations

Whether to include annotations.

type: bool

default: True

autodoc2_docstrings

Which objects to include docstrings for. ‘direct’ means only from objects that are not inherited.

type: “all” | “direct”

default: direct

autodoc2_sort_names

Whether to sort by name, when documenting, otherwise order by source

type: bool

default: False

autodoc2_replace_annotations

List of (from, to) for annotation replacements

type: list[tuple[str, str]]

default: []

autodoc2_replace_bases

List of (from, to) for class base replacements

type: list[tuple[str, str]]

default: []

autodoc2_index_template

The Jinja template for the top-level {output_dir}/index.rst, or None if no index should be written. The template will be passed a top_level variable, which is a list of top-level package/module names.

type: str | None

default:

API Reference
=============

This page contains auto-generated API reference documentation [#f1]_.

.. toctree::
   :titlesonly:
{% for package in top_level %}
   {{ package }}
{%- endfor %}

.. [#f1] Created with `sphinx-autodoc2 <https://github.com/chrisjsewell/sphinx-autodoc2>`_

Package analysis

In the autodoc2_packages configuration option, an item can be a string, or a dictionary such as:

autodoc2_packages = [
    "../src/autodoc2",
    {
        "path": "../src/other/module",
        "module": "other.module",
    },
]

The following are keys allowed in the dictionary:

autodoc2_packages[path]

The path to the package, relative to the source directory (POSIX format).

type: str

autodoc2_packages[from_git_clone]

Clone a git (url, branch/tag)/ If using this option the ‘path’ will be relative to root of the cloned repository.

type: tuple[str, str] | None

default: None

autodoc2_packages[module]

The module to use as the root of the package, otherwise the file/directory name is used.

type: str | None

default: None

autodoc2_packages[exclude_dirs]

Directories to exclude from module analysis (matched by fnmatch).

type: list[str]

default: ['__pycache__']

autodoc2_packages[exclude_files]

Files to exclude from module gathering (matched by fnmatch).

type: list[str]

default: []

autodoc2_packages[auto_mode]

Whether to automatically generate documentation for the package.

type: bool

default: True