Hide navigation sidebar
Hide table of contents sidebar
Skip to content
Back to top
View this page
Toggle table of contents sidebar

# 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`