lsst-sqre / documenteer

Sphinx extensions, configurations, and tooling for Rubin Observatory documentation projects
https://documenteer.lsst.io
MIT License
6 stars 3 forks source link

DM-15821: New directives for listing task topics #49

Closed jonathansick closed 6 years ago

jonathansick commented 6 years ago

The lsst-tasks, lsst-cmdlinetasks, lsst-pipelinetasks, lsst-configurables, and lsst-configs directives create listings of topics that are marked with lsst-task-topic or lsst-config-topic roles.

These listings not only link to the topic, but also show a summary that's either extracted from the corresponding docstring or set through the lsst-task-topic or lsst-config-topic directives.

These directives also generate a toctree, optionally.

Example usage in lsst.pipe.tasks:

Task reference
==============

Command-line tasks
------------------

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

Tasks
-----

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

Configurations
--------------

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

And here's some of the output:

screen shot 2018-09-27 at 1 48 47 pm