plasmapy_sphinx.automodsumm.core

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

automodsumm Directive

.. automodsumm::

The automodsumm directive is a wrapper on Sphinx’s autosummary directive and, as such, all the options for autosummary still work. The difference, where autosummary requires a list of all the objects to document, automodsumm only requires the module name and then it will inspect the module to find all the objects to be documented according to the listed options.

The module inspection will respect the __all__ dunder if defined; otherwise, it will inspect all objects of the module. The inspection will only gather direct sub-modules and ignore any 3rd party objects, unless listed in __all__.

The behavior of automodsumm can additionally be set with the configuration values described below.

: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, all groups will be included in the generated table.

Using the plasmapy_sphinx.automodsumm.core module as an example, the module’s API shows it is made of classes and functions. So the following yields,

.. automodsumm:: plasmapy_sphinx.automodsumm.core

or

.. automodsumm:: plasmapy_sphinx.automodsumm.core
   :groups: all

Automodsumm(name, arguments, options, ...)	The class that defines the automodsumm directive.
AutomodsummOptions(app, modname, options[, ...])	Class for advanced conditioning and manipulation of option arguments for plasmapy_sphinx.automodsumm.core.Automodsumm.
option_str_list(argument)	An option validator for parsing a comma-separated option argument.
setup(app)	Sphinx setup() function for the automodsumm functionality.

However, if you only want to collect classes then one could do

.. automodsumm:: plasmapy_sphinx.automodsumm.core
   :groups: classes

Automodsumm(name, arguments, options, ...)	The class that defines the automodsumm directive.
AutomodsummOptions(app, modname, options[, ...])	Class for advanced conditioning and manipulation of option arguments for plasmapy_sphinx.automodsumm.core.Automodsumm.

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

.. automodsumm:: plasmapy_sphinx.automodsumm.core
   :groups: classes, functions

:exclude-groups:

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

.. automodsumm:: plasmapy_sphinx.automodsumm.core
   :exclude-groups: functions

Automodsumm(name, arguments, options, ...)	The class that defines the automodsumm directive.
AutomodsummOptions(app, modname, options[, ...])	Class for advanced conditioning and manipulation of option arguments for plasmapy_sphinx.automodsumm.core.Automodsumm.

:skip:

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

.. automodsumm:: plasmapy_sphinx.automodsumm.core
   :skip: AutomodsummOptions, setup

Automodsumm(name, arguments, options, ...)	The class that defines the automodsumm directive.
option_str_list(argument)	An option validator for parsing a comma-separated option argument.

:toctree:

If you want the automodsumm table to serve as a toctree, then specify this option with a directory path DIRNAME with respect to the location of your conf.py file.

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

This will signal sphinx-autogen to generate stub files for the objects in the table and place them in the directory named by DIRNAME. This behavior respects the configuration value autosummary_generate. Additionally, automodsumm will not generate stub files for entry that falls into the modules group (see the automodsumm:groups option below), unless automodapi_generate_module_stub_files is set True.

automodsumm Configuration Values

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

automodapi_custom_groups

Configuration value used to define custom groups which are used by automodapi and automodsumm when sorting the discovered objects of an inspected module. An example custom group definition looks like

automodapi_custom_group = {
    "aliases": {
        "title": "Aliases",
        "description": "Aliases are ...",
        "dunder": "__aliases__",
    }
}

where the top-level key ("aliases") is the group name used in the automodsumm:groups option, "title" defines the title text of the group heading used by automodapi, "description" defines a brief description that will be placed after the title (item is optional and can be omitted) and "dunder" defines the name of a dunder variable (similar __all__) in the module. This dunder variable is defined at the top of the module being documented and defines a list of object names just like __all__. The automodapi and automodsumm directives will used this defined dunder to identify the objects associated with the custom group. Using plasmapy.formulary.speeds as an example, the aliases group can now be collected and displayed like

.. automodsumm:: plasmapy.formulary.speeds
   :groups: aliases

cs_(T_e, T_i, ion[, n_e, k, gamma_e, gamma_i, Z])	Alias to ion_sound_speed.
va_(B, density[, ion, mass_numb, Z])	Alias to Alfven_speed.
vth_(T, particle[, method, mass, ndim])	Alias to thermal_speed().
vth_kappa_(T, kappa, particle[, method, ...])	Alias to kappa_thermal_speed.

automodapi_generate_module_stub_files

(Default False) By default automodsumm will not generated stub files for the modules group, even when the sphinx configuration value autosummary_generate is set True. Setting this configure variable to True will cause stub files to be generated for the modules group.

autosummary_generate

Same as the autosummary configuration value autosummary_generate.

API

Classes

Automodsumm(name, arguments, options, ...)	The class that defines the automodsumm directive.
AutomodsummOptions(app, modname, options[, ...])	Class for advanced conditioning and manipulation of option arguments for plasmapy_sphinx.automodsumm.core.Automodsumm.

Functions

option_str_list(argument)	An option validator for parsing a comma-separated option argument.
setup(app)	Sphinx setup() function for the automodsumm functionality.