This topic is deprecated.

This topic has moved to the DM Developer guide at https://developer.lsst.io.


Not all of the content may have moved yet. If you want to help, please contribute to the https://github.com/lsst-dm/dm_dev_guide GitHub repository. For assistance, contact a DM Documentation Engineer in the #dm-square channel.

 

Doxygen is currently the mechanism by which detailed documentation is generated for DM-authored source code. This page offers pointers to on-line documentation, as well as tips for handling common situations that may require a little finesse. Veterans of DM documentation should record nuggets of expertise here. 

Documentation Reference Material

LSST Standards

Be sure to read the Documentation Standards, which is the official standard for the project.

Doxygen Reference Material

Not surprisingly, the best source for Doxygen knowledge is on-line:

  1. Doxygen home: http://www.stack.nl/~dimitri/doxygen/index.html
  2. Doxygen manual: http://www.stack.nl/~dimitri/doxygen/manual/index.html
  3. Markdown Support: http://www.stack.nl/~dimitri/doxygen/manual/markdown.html

Tips & Tricks

A few capabilities require a little special effort. Here are a few tips: 

  • Copy the doc string of the __init__ method:

    \copydoc \_\_init\_\_

  • To make Doxygen parse special commands within python docstrings, begin the string with an exclamation point: 

    """!Example command-line task that computes statistics on an image
 
\section pipeTasks_ExampleCmdLineTask_Contents Contents
  - \ref pipeTasks_ExampleCmdLineTask_Purpose
"""