plasmapy_sphinx.autodoc.automodapi

This module contains the functionality used to define the automodapi directive and its supporting configuration values.

automodapi Directive

.. automodapi::

The automodapi directive is a wrapper on Sphinx’s automodule directive and registered as one of the sphinx.ext.autodoc directives. As such, many of the automodule options still work, except any of the member options and ignore-module-all. The registration of automodapi with autodoc means automodapi is used by Sphinx when indexing the documented module.

automodapi is used to document modules (i.e. packages and .py files. The contents of the plasmapy_sphinx.utils page shows an example of how the following declaration is rendered.

`plasmapy_sphinx.utils`
=======================

.. automodapi:: plasmapy_sphinx.utils

The module level docstring is first rendered and then the categorized groups are rendered in automodsumm tables filtered for the associated group and placed under the appropriate object type heading. The order in which the automodsumm tables are displayed is controlled by the configuration value automodapi_group_order.

:groups:

When a module is inspected all the identified objects are categorized into groups. The built-in groups are:

modules	Direct sub-packages and modules.
classes	Python classes. (excluding exceptions and warnings)
exceptions	Classes that inherit from BaseException. (excluding warnings)
warnings	Classes that inherit from Warning.
functions	Objects that satisfy inspect.isroutine().
variables	All other objects.

In addition to the built-in groups, groups defined in automodapi_custom_groups will be categorized. When objects are collected and grouped the modules will be done first, followed by any custom group, and, finally, the built-in groups. By default, tables will be generated for all groups.

The contents of the API section below shows an example of how the follow declaration is rendered.

.. automodapi:: plasmapy_sphinx.autodoc.automodapi
   :no-main-docstring:

or

.. automodapi:: plasmapy_sphinx.autodoc.automodapi
   :no-main-docstring:
   :groups: all

The behavior of :no-main-docstring: is described below in the automodapi:no-main-docstring section. If you only want to display only classes, then the following can be done.

.. automodapi:: plasmapy_sphinx.autodoc.automodapi
   :no-main-docstring:
   :groups: classes

If you want to include multiple groups, then specify all groups as a comma separated list.

.. automodapi:: plasmapy_sphinx.autodoc.automodapi
   :groups: classes, functions

:exclude-groups:

This option behaves just like automodapi:groups except you are selectively excluding groups for the generated tables. Using the same example as before, a table of just classes can be generated by doing

.. automodapi:: plasmapy_sphinx.autodoc.automodapi
   :exclude-groups: functions

:no-groups:

Specify if you want to exclude all automodsumm tables from being generated.

.. automodapi:: plasmapy_sphinx.autodoc.automodapi
   :no-groups:

:skip:

This option allows you to skip (exclude) selected objects from the generated tables. The argument is given as a comma separated list of the object’s short name. Continuing with the example from above, let’s skip ModAPIDocumenter and setup from the tables.

.. automodapi:: plasmapy_sphinx.autodoc.automodapi
   :no-main-docstrings:
   :skip: ModAPIDocumenter, setup

Classes

AutomodapiOptions(app, modname, options[, ...])

Class for advanced conditioning and manipulation of option arguments of plasmapy_sphinx.autodoc.automodapi.ModAPIDocumenter.

:noindex:

Like the rest of Sphinx’s autodoc directives, automodapi is used by Sphinx to index the documented module and make available cross-referencing. To prevent multiple cross-references to the same documented module, :noindex: can be used to prevent the indexing.

.. automodapi:: plasmapy_sphinx.autodoc.automodapi
   :noindex:

:include-heading:

This option will create a top level heading for the documented module.

.. automodapi:: foo.bar
   :include-heading:

If bar is a package, then the heading will look like

foo.bar Package
---------------

and if bar is a .py file, then the heading will look like

foo.bar Module
--------------

:heading-chars:

(Default -^) A two character string specifying the underline characters used for the heading created by automodapi. The following code

.. automodapi:: foo.bar
   :include-heading:
   :heading-chars: ^~

would generate reStructuredText equivalent to

foo.bar Package
^^^^^^^^^^^^^^^

I am the main docstring

Sub-Packages & Modules
~~~~~~~~~~~~~~~~~~~~~~

.. automodsumm:: foo.bar
   :toctree: api
   :groups: modules

If automodapi:include-heading is not given, then the first character will be used for the automodsumm table headings.

:toctree:

If you want the tables generated by automodapi to serve as toctree’s, then specify this option with a directory path DIRNAME with respect to the location of your conf.py.

.. automodapi:: plasmapy_sphinx.autodoc.automodapi
   :toctree: DIRNAME

If :toctree: is not set, then DIRNAME will default to what is set by automodapi_default_toctree_dir. If no toctree is desired, then use option automodapi:no-toctree.

:no-toctree:

Use this option if you do not want the tables generated by automodapi to serve as toctree’s.

.. automodapi:: plasmapy_sphinx.autodoc.automodapi
   :no-toctree:

:no-main-docstring:

By default the module level docstring will be rendered and displayed, but setting this option will omit the module level docstring and leave just the autosummary tables for each collected group of objects.

.. automodapi:: plasmapy_sphinx.autodoc.automodapi
   :no-main-docstring:

:inheritance-diagram:

Set this option to generate inheritance diagrams (using the directive inheritance-diagram) for the groups listed in the configuration value automodapi_groups_with_inheritance_diagrams. Default behavior is controlled by the configuration value automodapi_include_inheritance_diagram. The option automodapi:no-inheritance-diagram will supersede this option.

.. automodapi:: plasmapy_sphinx.autodoc.automodapi
   :inheritance-diagram:

:no-inheritance-diagram:

Set this option to not generate inheritance diagrams. This option will take precedence over the automodapi:inheritance-diagram option.

.. automodapi:: plasmapy_sphinx.autodoc.automodapi
   :no-inheritance-diagram:

automodapi Configuration Values

A configuration value is a variable that can be defined in conf.py to configure the default behavior of related sphinx directives. The configuration values below relate to the behavior of the automodapi directive.

automodapi_default_toctree_dir

(Default "api") The default directory name, with respect to conf.py, for automodapi to write stub files to. This is the default value for automodapi:toctree.

automodapi_group_order

(Default ("modules", "classes", "exceptions", "warnings", "functions", "variables")) A tuple defining the order automodapi should display the collected groups. If automodapi identifies groups that are not identified here (e.g. unlisted custom groups), then those groups will be displayed alphabetically after the groups defined in automodapi_group_order. This configuration value should be defined if custom groups are defined by automodapi_custom_groups .

automodapi_groups_with_inheritance_diagrams

(Default ["classes", "exceptions", "warnings"]) A list defining which groups should have inheritance diagrams associated with them when displayed by automodapi.

automodapi_include_inheritance_diagram

(Default True) Controls if automodapi will by default generated inheritance diagrams (see directive inheritance-diagram) for a given group. The groups that should get inheritance diagrams are defined by the configuration value automodapi_groups_with_inheritance_diagrams.

API

Classes

AutomodapiOptions(app, modname, options[, ...])	Class for advanced conditioning and manipulation of option arguments of plasmapy_sphinx.autodoc.automodapi.ModAPIDocumenter.
ModAPIDocumenter(*args)	The class that defines the autodoc directive automodapi.

Functions

setup(app)

Sphinx setup() function for the automodapi functionality.