config-topic-type.rst

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 :doc:`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:

.. remote-code-block:: https://raw.githubusercontent.com/lsst/templates/master/file_templates/config_topic/lsst.example.ExampleConfig.rst
   :language: rst

The next sections describe the key components of config topics.

File name and location

Config topic files are located in the :file:`configs/` subdirectory of the :ref:`module documentation directory <docdir-module-doc-directories>` 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 :rst:dir:`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 :rst:role:`lsst-config` role:

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

In addition, other pages can use the :rst:dir:`lsst-configs` directive to automatically list config pages that are marked by an :rst:dir:`lsst-config-topic` directive. See the :doc:`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 :rst:role:`lsst-task` role.

Configuration fields

This section lists the configuration fields that the config class provides. The listing is similar to the :ref:`task-topic-configs` of task configs.

The only content of this section in the reStructuredText file is a :rst:dir:`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.