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	plasmapy_sphinx.autodoc contains functionality that extends sphinx.ext.autodoc.
automodsumm	plasmapy_sphinx.automodsumm contains functionality that defines the automodsumm directive, and the associated automatic stub file generation for the documented items in the generated automodsumm tables.
directives	plasmapy_sphinx.directives defines directives and roles that do not fall under the scopes of autodoc or automodsumm.
ext	The plasmapy_sphinx.ext module contains all the sphinx setup() functions for all available extensions.
theme	The PlasmaPy theme is a Sphinx theme that inherits from the sphinx_rtd_theme.
utils	A utility package containing functions and variables to support development of the core functionality in plasmapy_sphinx.

Variables & Attributes

__version__

plasmapy_sphinx version string