plasmapy_sphinx: The Sphinx extension package for PlasmaPy

This Sphinx extension package contains custom documentation functionality used to document PlasmaPy’s packages .

Installation

This package is currently not released in any form and can only be obtained by installing plasmapy directly from its GitHub repository. We do plan to breakout plasmapy_sphinx into its own repository and release it to https://pypi.org at a future date.

Setup

To enable plasmapy_sphinx’s functionality it needs to be added to the extensions configuration value in your conf.py file.

extensions = ["plasmapy_sphinx"]

If you don’t want all of plasmapy_sphinx’s functionality, then any module containing a Sphinx setup() function can be activated independently. For example, you can just implement the automodapi functionality by setting up the plasmapy_sphinx.autodoc.automodapi module like…

extensions = ["plasmapy_sphinx.autodoc.automodapi"]

The Rundown

plasmapy_sphinx.autodoc

The plasmapy_sphinx.autodoc sub-package contains functionality that extends sphinx.ext.autodoc. The defined directives are registered as sphinx.ext.autodoc directives and, thus, will behave similarly to autoclass, autofunction, etc. and work with sphinx.ext.autosummary and plasmapy_sphinx.automodsumm.

plasmapy_sphinx.automodsumm

The plasmapy_sphinx.automodsumm sub-package is an evolution of sphinx.ext.autosummary and was adapted from sphinx_automodapi.automodsumm. Unlike the autosummary directive where you have to manually list all the objects/members to appear in the summary table, the automodsumm directive will inspect a given module and automatically populate the summary table with the detected objects/members.

plasmapy_sphinx.directives

This sub-package contains custom reStructuredText directives and roles that do not fall under plasmapy_sphinx.autodoc or plasmapy_sphinx.automodsumm.

API

Sub-Packages & Modules

autodoc	This sub-package contains functionality that extends sphinx.ext.autodoc.
automodsumm	This sub-package contains functionality that defines the automodsumm directive and the stub file generation for items listed in automodsumm tables.
directives	This sub-package defines directives and roles that do not fall under the scopes of autodoc or automodsumm.
utils	A utility package containing functions and variables to support development of the core functionality in plasmapy_sphinx.

Functions

setup(app)

The sphinx setup() function for the plasmapy_sphinx extension.