Sphinx extensions

This page gives the API for the custom Sphinx extensions used in Astropy.

automodapi Extension

This sphinx extension adds a tools to simplify generating the API documentationfor Astropy packages and affiliated packages.

automodapi directive

This directive takes a single argument that must be module or package. It will produce a block of documentation that includes the docstring for the package, an automodsumm directive, and an automod-diagram if there are any classes in the module.

It accepts the following options:

  • :no-inheritance-diagram:

    If present, the inheritance diagram will not be shown even if the module/package has classes.

  • :skip: str

    This option results in the specified object being skipped, that is the object will not be included in the generated documentation. This option may appear any number of times to skip multiple objects.

  • :no-main-docstr:

    If present, the docstring for the module/package will not be generated. The function and class tables will still be used, however.

  • :headings: str

    Specifies the characters (in one string) used as the heading levels used for the generated section. This must have at least 2 characters (any after 2 will be ignored). This also must match the rest of the documentation on this page for sphinx to be happy. Defaults to “-^”, which matches the convention used for Python’s documentation, assuming the automodapi call is inside a top-level section (which usually uses ‘=’).

This extension also adds a sphinx configuration option automodapi_toctreedirnm. It must be a string that specifies the name of the directory the automodsumm generated documentation ends up in. This directory path should be relative to the documentation root (e.g., same place as index.rst). It defaults to ‘_generated’

automodsumm Extension

This sphinx extension adds two directives for summarizing the public members of a module or package.

These directives are primarily for use with the automodapi extension, but can be used independently.

automodsumm directive

This directive will produce an “autosummary”-style table for public attributes of a specified module. See the sphinx.ext.autosummary extension for details on this process. The main difference from the autosummary directive is that autosummary requires manually inputting all attributes that appear in the table, while this captures the entries automatically.

This directive requires a single argument that must be a module or package.

It also accepts any options supported by the autosummary directive- see sphinx.ext.autosummary for details. It also accepts two additional options:

  • :classes-only:

    If present, the autosummary table will only contain entries for classes. This cannot be used at the same time with :functions-only: .

  • :functions-only:

    If present, the autosummary table will only contain entries for functions. This cannot be used at the same time with :classes-only: .

  • :skip: obj1, [obj2, obj3, ...]

    If present, specifies that the listed objects should be skipped and not have their documentation generated, nor be includded in the summary table.

automod-diagram directive

This directive will produce an inheritance diagram like that of the sphinx.ext.inheritance_diagram extension.

This directive requires a single argument that must be a module or package. It accepts no options.

Note

Like ‘inheritance-diagram’, ‘automod-diagram’ requires graphviz to generate the inheritance diagram.

Numpydoc Extension

This extension is a port of the numpydoc extentension written by the numpy and scipy projects, with some tweaks for Astropy. See the code for details, as it is quite complex and includes a variety of interrelated extensions.