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’sautomodule
directive and registered as one of thesphinx.ext.autodoc
directives. As such, many of theautomodule
options still work, except any of the member options and ignore-module-all. The registration ofautomodapi
withautodoc
meansautomodapi
is used by Sphinx when indexing the documented module.automodapi
is used to document modules (i.e. packages and.py
files. The contents of theplasmapy_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 theautomodsumm
tables are displayed is controlled by the configuration valueautomodapi_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 theautomodapi: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
andsetup
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 likefoo.bar Package ---------------
and if
bar
is a.py
file, then the heading will look likefoo.bar Module --------------
- :heading-chars:
(Default
-^
) A two character string specifying the underline characters used for the heading created byautomodapi
. The following code.. automodapi:: foo.bar :include-heading: :heading-chars: ^~
would generate reStructuredText equivalent to
foo.bar Package ^^^^^^^^^^^^^^^ I am the main docstring Subpackages & Modules ~~~~~~~~~~~~~~~~~~~~~ .. automodsumm:: foo.bar :toctree: api :groups: modules
If
automodapi:include-heading
is not given, then the first character will be used for theautomodsumm
table headings.
- :toctree:
If you want the tables generated by
automodapi
to serve astoctree
’s, then specify this option with a directory pathDIRNAME
with respect to the location of yourconf.py
... automodapi:: plasmapy_sphinx.autodoc.automodapi :toctree: DIRNAME
If
:toctree:
is not set, thenDIRNAME
will default to what is set byautomodapi_default_toctree_dir
. If notoctree
is desired, then use optionautomodapi:no-toctree
.
- :no-toctree:
Use this option if you do not want the tables generated by
automodapi
to serve astoctree
’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 valueautomodapi_groups_with_inheritance_diagrams
. Default behavior is controlled by the configuration valueautomodapi_include_inheritance_diagram
. The optionautomodapi: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 toconf.py
, forautomodapi
to write stub files to. This is the default value forautomodapi:toctree
.
- automodapi_group_order
(Default
("modules", "classes", "exceptions", "warnings", "functions", "variables")
) A tuple defining the orderautomodapi
should display the collected groups. Ifautomodapi
identifies groups that are not identified here (e.g. unlisted custom groups), then those groups will be displayed alphabetically after the groups defined inautomodapi_group_order
. This configuration value should be defined if custom groups are defined byautomodapi_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 byautomodapi
.
- automodapi_include_inheritance_diagram
(Default
True
) Controls ifautomodapi
will by default generated inheritance diagrams (see directiveinheritance-diagram
) for a given group. The groups that should get inheritance diagrams are defined by the configuration valueautomodapi_groups_with_inheritance_diagrams
.
API
Classes
|
Class for advanced conditioning and manipulation of option arguments of |
|
The class that defines the |

Functions
|
Sphinx |