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.