Config topic type

Config classes (subclasses of lsst.pex.config.Config) are typically associated with a task class and are documented as part of the Task topic type. Some config classes stand alone, but are used used in tasks through a ConfigField configuration field. For example, the lsst.pipe.tasks.photoCal.PhotoCalTask has a colorterms configuration field that points to a standalone lsst.pipe.tasks.colorterms.ColortermLibrary config class. This page describes how to document config classes like ColortermLibrary.

Starter template

The config topic file template is available in the lsst/templates repository.

Note

The config topic file template sets technical details like labels for sections, names of sections, and ordering of sections. Starting from the template is the best way to follow the config topic standard.

For an example config named lsst.example.ExampleConfig, the rendered template looks like this:

.. lsst-config-topic:: lsst.example.ExampleConfig

#############
ExampleConfig
#############

``ExampleConfig`` provides configuration for ...

.. _lsst.example.ExampleConfig-configs:

Configuration fields
====================

.. lsst-config-fields:: lsst.example.ExampleConfig

The next sections describe the key components of config topics.

File name and location

Config topic files are located in the configs/ subdirectory of the module documentation directory within a package. The page itself is named after the fully-qualified name of the config class with a .rst extension.

For example, suppose a standalone config class is lsst.pipe.tasks.colorterms.Colorterm. Its config topic page is located in the pipe_tasks package directory like this:

.
└── doc
    └── lsst.pipe.tasks
        ├── index.rst
        └── configs
            └── lsst.pipe.tasks.colorterms.Colorterm.rst

Preamble

The lsst-config-topic directive at the top of the page declares that the page is a canonical reference for the specified config class. For example:

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

Through this directive, other pages can reference this config using the lsst-config role:

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

In addition, other pages can use the lsst-configs directive to automatically list config pages that are marked by an lsst-config-topic directive. See the Module homepage topic type for an example of this strategy.

Title

The title is the name of the config class (without its module name). No special code formatting is applied to the title.

Context paragraph

Directly below the title, write a paragraph or two (though not many) that describe what the config is for. Link to any related tasks using the lsst-task role.

Configuration fields

This section lists the configuration fields that the config class provides. The listing is similar to the Configuration fields section of task configs.

The only content of this section in the reStructuredText file is a lsst-config-fields directive. The fully-qualified name of the config class is the directive’s sole argument.

For example:

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

In depth section

If necessary, you can provide an extended discussion of the configuration in this section. Feel free to include examples as necessary.

Omit this section if there isn’t any content for it.