Package toctree extension for LSST Stack documentation

Documenteer provides the package-toctree module-toctree directives that are useful building dynamic toctrees of package and module documentation in stack documentation projects like the LSST Science Pipelines (https://pipelines.lsst.io).

To use this Sphinx extension, add documenteer.sphinxext.packagetoctree to your conf.py file:

extensions = ["documenteer.sphinxext.packagetoctree"]

To learn more about the build process for stack documentation projects, see Overview of the pipelines.lsst.io build system.

Summary

Directives

Directive	Purpose
package-toctree	Create a toctree of package homepages.
module-toctree	Create a toctree of module homepages.

Directives

.. package-toctree::

The package-toctree directive creates a toctree of package documentation homepages found in a stack documentation project. Stack packages have index pages with paths /packages/{{name}}/index.rst within project. For more information about package documentation homepages, see the Layout of the doc/ directory and Package homepage topic type pages in the LSST DM Developer Guide.

Basic example:

.. package-toctree::

Options

skip: package-list

To exclude specific EUPS packages from the toctree, provide a comma-separated list of EUPS package names:

.. package-toctree::
   :skip: afw, utils

.. module-toctree::

The module-toctree directive creates a toctree of module documentation homepages found in a stack documentation project. Modules have index pages with paths /module/{{name}}/index.rst within a Stack documentation project. For more information about module documentation homepages, see the Layout of the doc/ directory and Module homepage topic type pages in the LSST DM Developer Guide.

Basic example:

.. module-toctree::

Options

skip: module-list

To exclude specific modules from the toctree, provide a comma-separated list of module names:

.. module-toctree::
   :skip: lsst.afw.image, lsst.afw.fits