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.parameters as an example, the aliases group can now be collected and displayed like

.. automodsumm:: plasmapy.formulary.parameters
   :groups: aliases

betaH_(n, T, B, ion, particle[, ...])

Alias to Hall_parameter.

cs_(T_e, T_i, ion[, n_e, k, gamma_e, ...])

Alias to ion_sound_speed.

cwp_(n, particle)

Alias to inertial_length.

DB_(T_e, B)

Alias to Bohm_diffusion.

lambdaD_(T_e, n_e)

Alias to Debye_length.

nD_(T_e, n_e)

Alias to Debye_number.

oc_(B, particle[, signed, Z, to_hz])

Alias to gyrofrequency.

pmag_(B)

Alias to magnetic_pressure.

pth_(T, n)

Alias to thermal_pressure.

rc_(B, particle, *[, Vperp, T_i, T])

Alias to gyroradius.

rho_(density, particle[, z_ratio])

Alias to mass_density.

rhoc_(B, particle, *[, Vperp, T_i, T])

Alias to gyroradius.

ub_(B)

Alias to magnetic_energy_density.

va_(B, density[, ion, z_mean])

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.

wc_(B, particle[, signed, Z, to_hz])

Alias to gyrofrequency.

wlh_(B, n_i, ion[, to_hz])

Alias to lower_hybrid_frequency.

wp_(n, particle[, z_mean, to_hz])

Alias to plasma_frequency.

wuh_(B, n_e[, to_hz])

Alias to upper_hybrid_frequency.

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.

Inheritance diagram of plasmapy_sphinx.automodsumm.core.Automodsumm, plasmapy_sphinx.automodsumm.core.AutomodsummOptions

Functions

option_str_list(argument)

An option validator for parsing a comma-separated option argument.

setup(app)

Sphinx setup() function for the automodsumm functionality.