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. The documenteer.sphinxconfig.stackconf 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:: 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:: 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:

Topic markers

These directives mark task and configuration topic types:

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.

Example:

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

Mark the page as a standalone configuration topic.

Required argument:

  • Name of the config class.

Example:

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

Cross-reference roles

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

: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.