配置选项

autoapi_dirs

必需

您希望从中生成 API 文档的源代码的路径（相对或绝对路径）。这些路径会递归搜索与 autoapi_file_patterns 匹配的文件。相对路径应相对于文档的源目录。

对于 Python，如果指定了包目录，包目录本身将包含在子目录的相对路径中。如果指定了普通目录，则该目录将不会包含在相对路径中。

autoapi_template_dir

默认值： ''

用户定义的模板目录，用于覆盖我们的默认模板。路径可以是绝对的，也可以是相对于文档源目录的。注意：相对于 sphinx-build 运行的路径仅用于向后兼容。将来的版本将删除此路径。

您可以查看默认模板，请参阅 Sphinx AutoAPI 软件包的 autoapi/templates 目录。

autoapi_file_patterns

默认： ['*.py', '*.pyi']

当生成文档时，要查找的文件模式列表。例如，如果 autoapi_file_patterns 设置为默认值，并且找到 .py 文件和 .pyi 文件，那么 .py 文件将被读取。

autoapi_generate_api_docs

默认值： True

是否生成 API 文档。如果此选项为 False，则应通过 指令 生成文档。

自定义选项

autoapi_options

默认值： [ 'members', 'undoc-members', 'private-members', 'show-inheritance', 'show-module-summary', 'special-members', 'imported-members', ]

显示生成的文档的选项。

  • members: 显示对象的子项

  • inherited-members: Display children of an object that have been inherited from a base class. Members from standard library base classes are not included, unless the base class is abstract.

  • undoc-members: Display objects that have no docstring

  • private-members: Display private objects (eg. _foo in Python)

  • special-members: Display special objects (eg. __foo__ in Python)

  • show-inheritance: Display a list of base classes below the class signature.

  • show-inheritance-diagram: Display an inheritance diagram in generated class documentation. It makes use of the sphinx.ext.inheritance_diagram extension, and requires Graphviz to be installed.

  • show-module-summary: Whether to include autosummary directives in generated module documentation.

  • imported-members: For objects imported into a package, display objects imported from the same top level package or module. This option does not effect objects imported into a module.

autoapi_ignore

Default: ['*migrations*']

A list of patterns to ignore when finding files.

autoapi_root

Default: autoapi

Path to output the generated AutoAPI files into, including the generated index page. This path must be relative to the source directory of your documentation files. This can be used to place the generated documentation anywhere in your documentation hierarchy.

autoapi_add_toctree_entry

默认值： True

Whether to insert the generated documentation into the TOC tree. If this is False, the default AutoAPI index page is not generated and you will need to include the generated documentation in a TOC tree entry yourself.

autoapi_python_class_content

Default: class

Which docstring to insert into the content of a class.

  • class: Use only the class docstring.

  • both: Use the concatenation of the class docstring and the __init__ docstring.

  • init: Use only the __init__ docstring.

If the class does not have an __init__ or the __init__ docstring is empty and the class defines a __new__ with a docstring, the __new__ docstring is used instead of the __init__ docstring.

autoapi_member_order

Default: bysource

The order to document members. This option can have the following values:

  • alphabetical: Order members by their name, case sensitively.

  • bysource: Order members by the order that they were defined in the source code.

  • groupwise: Order members by their type then alphabetically, ordering the types as follows:

    • Submodules and subpackages

    • Attributes

    • Exceptions

    • Classes

    • Functions

    • Methods

autoapi_python_use_implicit_namespaces

Default: False

This changes the package detection behaviour to be compatible with PEP 420, but directories in autoapi_dirs are no longer searched recursively for packages. Instead, when this is True, autoapi_dirs should point directly to the directories of implicit namespaces and the directories of packages.

If searching is still required, this should be done manually in the conf.py.

autoapi_prepare_jinja_env

Default: None

A callback that is called shortly after the Jinja environment is created. The callback is passed the Jinja environment for editing before template rendering begins.

The callback should have the following signature:

prepare_jinja_env(jinja_env: jinja2.Environment) → None
autoapi_own_page_level

Default: 'module'

This configuration value specifies the level at which objects are rendered on a single page. Valid levels, in descending order of hierarchy, are as follows:

  • module: Packages, modules, subpackages, and submodules.

  • class: Classes, exceptions, and all object types mentioned above.

  • function: Functions, and all object types mentioned above.

  • method: Methods, and all object types mentioned above.

  • attribute: Class and module level attributes, properties, and all object types mentioned above.

Events

The following events allow you to control the behaviour of AutoAPI.

autoapi-skip-member(app, what, name, obj, skip, options)

Emitted when a template has to decide whether a member should be included in the documentation. Usually the member is skipped if a handler returns True, and included otherwise. Handlers should return None to fall back to the default skipping behaviour of AutoAPI or another attached handler.

Example conf.py
def skip_util_classes(app, what, name, obj, skip, options):
    if what == "class" and "util" in name:
       skip = True
    return skip

def setup(sphinx):
   sphinx.connect("autoapi-skip-member", skip_util_classes)
Parameters:

  • app -- The Sphinx application object.

  • what (str) -- The type of the object which the docstring belongs to. This can be one of: "attribute", "class", "data", "exception", "function", "method", "module", "package".

  • name (str) -- The fully qualified name of the object.

  • obj (PythonPythonMapper) -- The object itself.

  • skip (bool) -- Whether AutoAPI will skip this member if the handler does not override the decision.

  • options -- The options given to the directive.

Advanced Options

autoapi_keep_files

Default: False

Keep the AutoAPI generated files on the filesystem after the run. Useful for debugging or transitioning to manual documentation.

Keeping files will also allow AutoAPI to use incremental builds. Providing none of the source files have changed, AutoAPI will skip parsing the source code and regenerating the API documentation.

Suppressing Warnings

suppress_warnings

This is a sphinx builtin option that enables the granular filtering of AutoAPI generated warnings.

Items in the suppress_warnings list are of the format "type.subtype" where ".subtype" can be left out to cover all subtypes. To suppress all AutoAPI warnings add the type "autoapi" to the list:

suppress_warnings = ["autoapi"]

If narrower suppression is wanted, the available subtypes for AutoAPI are:

  • python_import_resolution: Emitted if resolving references to objects in an imported module failed. Potential reasons include cyclical imports and missing (parent) modules.

  • not_readable: Emitted if processing (opening, parsing, ...) an input file failed.

  • toc_reference: Emitted if a reference to an entry in a table of content cannot be resolved.

  • nothing_rendered: Emitted if nothing was found to be documented. Potential reasons include no files being found in autoapi_dirs that match autoapi_file_patterns, or all discovered modules and objects being excluded from rendering due to autoapi_options or other rendering exclusions.

So if all AutoAPI warnings concerning unreadable sources and failing Python imports should be filtered, but all other warnings should not, the option would be

suppress_warnings = ["autoapi.python_import_resolution", "autoapi.not_readable"]