Configuration Options
*********************

autoapi_dirs

   **Required**

   Paths (relative or absolute) to the source code that you wish to
   generate your API documentation from. The paths are searched
   recursively for files matching "autoapi_file_patterns". Relative
   paths should be relative to the source directory of your
   documentation.

   For Python, if a package directory is specified, the package
   directory itself will be included in the relative path of the
   children. If an ordinary directory is specified, that directory
   will not be included in the relative path.

autoapi_template_dir

   Default: "''"

   A directory that has user-defined templates to override our default
   templates. The path can either be absolute, or relative to the
   source directory of your documentation files. An path relative to
   where *sphinx-build* is run is allowed for backwards compatibility
   only and will be removed in a future version.

   You can view the default templates in the autoapi/templates
   directory of the package.

autoapi_file_patterns

   Default: "['*.py', '*.pyi']"

   A list containing the file patterns to look for when generating
   documentation. Patterns should be listed in order of preference.
   For example, if "autoapi_file_patterns" is set to the default value
   and a *.py* file and a *.pyi* file are found, then the *.py* will
   be read.

autoapi_generate_api_docs

   Default: "True"

   Whether to generate API documentation. If this is "False",
   documentation should be generated though the Directives.


Customisation Options
=====================

autoapi_options

   Default: [ "'members'", "'undoc-members'", "'private-members'",
   "'show-inheritance'", "'show-module-summary'", "'special-members'",
   "'imported-members'", ]

   Options for display of the generated documentation.

   * "members": Display children of an object

   * "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 directories and files to
   document.

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

   Default: "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"]
