Sphinx extensions for the LSST Science Pipelines task framework

These extensions allow you to document and reference tasks in the LSST Science Pipelines.

Enable these extensions by adding documenteer.sphinxext.lssttasks to the Sphinx project’s extensions configuration list.

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

extensions = ["documenteer.sphinxext.lssttasks"]

The documenteer.conf.pipelines and documenteer.conf.pipelinespkg configurations automatically add these extensions to LSST Science Pipelines package documentation projects.

Listing configuration fields

These directives list configuration fields associated with a task or configuration class:

• lsst-task-config-fields

• lsst-task-config-subtasks

• lsst-config-fields

.. lsst-task-config-fields:: task_name

List the configuration fields (except for ConfigurableField and Registry) for a task class.

Use this directive in the “Configuration fields” component of Task documentation topics.

Required argument:

• Name of the task class.

Example:

.. lsst-task-config-fields:: lsst.pipe.tasks.processCcd.ProcessCcdTask

See also:

• lsst-task-config-subtasks: lists subtasks instead of general configuration fields.

• lsst-config-field: role for cross-referencing individual fields documented with this directive.

.. lsst-task-config-subtasks:: task_name

List the subtask configuration fields (ConfigurableField and Registry types) for a task class.

Use this directive in the “Configurable subtasks” component of Task documentation topics.

Required argument:

• Name of the task class.

Example:

.. lsst-task-config-subtasks:: lsst.pipe.tasks.processCcd.ProcessCcdTask

See also:

• lsst-task-config-fields: lists general configuration fields (not of the ConfigurableField and Registry types).

• lsst-config-field: role for cross-referencing individual fields documented with this directive.

.. lsst-config-fields:: config_name

List all configuration fields associated with a configuration class (subclass of lsst.pex.config.Config).

Use this directive in standalone configuration topics.

Required argument:

• Name of the config class.

Example:

.. lsst-config-fields:: lsst.pipe.tasks.colorterms.Colorterm

See also:

• Use lsst-task-config-fields or lsst-task-config-subtasks to list configuration fields when working within a task topic.

• lsst-config-field: role for cross-referencing individual fields documented with this directive.

Topic markers

These directives mark task and configuration topic types:

• lsst-task-topic

• lsst-config-topic

Use these directives at the top of either a task or standalone config topic page.

.. lsst-task-topic:: task_name

Mark the page as a task topic.

Required argument:

• Name of the task class.

Content:

You can optionally add a one or two sentence summary of the task as the directive’s content. This summary is used by the topic listing directives. This content is optional. If not set, the summary is set from the task’s docstring.

Example:

.. lsst-task-topic:: lsst.pipe.tasks.processCcd.ProcessCcdTask

   Summary of ProcessCcdTask.

.. lsst-config-topic:: config_name

Mark the page as a standalone configuration topic.

Required argument:

• Name of the config class.

Content:

You can optionally add a one or two sentence summary of the config as the directive’s content. This summary is used by the topic listing directives. This content is optional. If not set, the summary is set from the config’s docstring.

Example:

.. lsst-config-topic:: lsst.pipe.tasks.colorterms.Colorterm

   Summary of Colorterm.

Topic listings

These directives make listings of topics labeled by topic markers:

• lsst-tasks

• lsst-cmdlinetasks

• lsst-pipelinetasks

• lsst-configurables

• lsst-configs

.. lsst-tasks::

List task topics that are marked with the lsst-task-topic directive. Only lsst.pipe.base.Task-types that are not CmdLineTask or PipelineTask-types are listed by this directive.

Options

root

The root Python package that tasks must belong to to be including in the listing. For example, :root: lsst.pipe.tasks means that only tasks in the lsst.pipe.tasks Python subpackage are included in the listing.

toctree

If set, a toctree is automatically generated for pages that appear in a given directory. For example, if task topics are in a tasks/ subdirectory, set :toctree: tasks. The toctree is hidden.

If this directive is listing topics that are already included by another toctree, don’t set this option.

Note that toctree doesn’t filter tasks using the same critera as the root option. Generally the directory structure should be set up so that toctree effectively corresponds to the filtering criteria set by root, though.

Example:

.. lsst-tasks::
   :root: lsst.pipe.tasks
   :toctree: tasks

.. lsst-cmdlinetasks::

List task topics that are marked with the lsst-task-topic directive that correspond to lsst.pipe.base.CmdLineTask-types.

Options

root

The root Python package that tasks must belong to to be including in the listing. For example, :root: lsst.pipe.tasks means that only tasks in the lsst.pipe.tasks Python subpackage are included in the listing.

toctree

If set, a toctree is automatically generated for pages that appear in a given directory. For example, if task topics are in a tasks/ subdirectory, set :toctree: tasks. The toctree is hidden.

If this directive is listing topics that are already included by another toctree, don’t set this option.

Note that toctree doesn’t filter tasks using the same critera as the root option. Generally the directory structure should be set up so that toctree effectively corresponds to the filtering criteria set by root, though.

Example:

.. lsst-cmdlinetasks::
   :root: lsst.pipe.tasks
   :toctree: tasks

.. lsst-pipelinetasks::

List task topics that are marked with the lsst-task-topic directive that correspond to lsst.pipe.base.PipelineTask-types.

Options

root

The root Python package that tasks must belong to to be including in the listing. For example, :root: lsst.pipe.tasks means that only tasks in the lsst.pipe.tasks Python subpackage are included in the listing.

toctree

If set, a toctree is automatically generated for pages that appear in a given directory. For example, if task topics are in a tasks/ subdirectory, set :toctree: tasks. The toctree is hidden.

If this directive is listing topics that are already included by another toctree, don’t set this option.

Note that toctree doesn’t filter tasks using the same critera as the root option. Generally the directory structure should be set up so that toctree effectively corresponds to the filtering criteria set by root, though.

Example:

.. lsst-pipelinetasks::
   :root: lsst.pipe.tasks
   :toctree: tasks

.. lsst-configurables::

List “configurable” topics that are marked with the lsst-task-topic directive that correspond to generic configurable types.

Options

root

The root Python package that configurables must belong to to be including in the listing. For example, :root: lsst.pipe.tasks means that only configurables in the lsst.pipe.tasks Python subpackage are included in the listing.

toctree

If set, a toctree is automatically generated for pages that appear in a given directory. For example, if configurable topics are in a configurables/ subdirectory, set :toctree: configurables. The toctree is hidden.

If this directive is listing topics that are already included by another toctree, don’t set this option.

Example:

.. lsst-configurables::
   :root: lsst.pipe.tasks
   :toctree: configurables

.. lsst-configs::

List “config” topics that are marked with the lsst-config-topic directive that correspond to lsst.pex.config.Config-types.

Options

root

The root Python package that configs must belong to to be including in the listing. For example, :root: lsst.pipe.tasks means that only configs in the lsst.pipe.tasks Python subpackage are included in the listing.

toctree

If set, a toctree is automatically generated for pages that appear in a given directory. For example, if configurable topics are in a configurables/ subdirectory, set :toctree: configurables. The toctree is hidden.

If this directive is listing topics that are already included by another toctree, don’t set this option.

Note that toctree doesn’t filter tasks using the same critera as the root option. Generally the directory structure should be set up so that toctree effectively corresponds to the filtering criteria set by root, though.

Example:

.. lsst-configs::
   :root: lsst.pipe.tasks
   :toctree: configs

Cross-reference roles

These roles link to task or config topic pages and to individual configuration fields.

• lsst-task

• lsst-config

• lsst-config-field

:lsst-task:

Reference a task topic that is marked with the lsst-task-topic directive.

:lsst-task:`lsst.pipe.tasks.processCcd.ProcessCcdTask`

The link text can be shortened to just the task class name by prefixing the class with ~:

:lsst-task:`~lsst.pipe.tasks.processCcd.ProcessCcdTask`

You can also provide alternative link text:

:lsst-task:`this task <lsst.pipe.tasks.processCcd.ProcessCcdTask>`

:lsst-config:

Reference a standalone config topic that marked with the lsst-config-topic directive.

:lsst-config:`lsst.pipe.tasks.colorterms.Colorterm`

Abbreviate the link to just the class name:

:lsst-config:`~lsst.pipe.tasks.colorterms.Colorterm`

Provide alternative link text:

:lsst-config:`this config <lsst.pipe.tasks.colorterms.Colorterm>`

:lsst-config-field:

Reference a configuration field.

Note that you must reference a configuration field as an attribute of a configuration class, not as an attribute of task class’s config attribute.

:lsst-config-field:`lsst.pipe.tasks.processCcd.ProcessCcdConfig.isr`

See also:

The lsst-task-config-fields, lsst-task-config-subtasks, and lsst-config-fields directives create the configuration field documentation that this role references.

Task interface directives

.. lsst-task-api-summary:: task_name

Generate a summary of the task’s Python API.

Required argument:

• Name of the task class.

Example:

.. lsst-task-api-summary:: lsst.pipe.tasks.assembleCoadd.AssembleCoaddTask