Page History

Tasks should be documented in the .py file, adding an entry to the doxygen group LSST_Task_Documentation group, e.g.

## \addtogroup LSST_task_documentation
## \{
## \page sourceDetectionTask
## \ref SourceDetectionTask_ "SourceDetectionTask"
## \copybrief SourceDetectionTask
## \}

It is acceptable to make documentation only changes on master.  If you feel the need to clean things up you may do it as part of the documentation, but as a short-lived branch.

I warned you a fortnight or so ago that we needed P1 ("Priority 1") task documentation written before the Phoenix meeting in August.  I took advantage of the PanSTARRS meeting this week to make a bit more progress on some of my tasks, with the intention of learning a bit more about how we should go about the task.  My first version used an external .dox file, but it turns out that it's quite easy to generate the desired docs in the Task's .py file.  There are a couple of tricks:

• Remember that only """! ... """ comments are fully processed by doxygen
• I use \copydoc to get the method docs into the "right place".  Russell points out that you have to write {{ \_\_init\_\_}}

Task documentation will appear at http://lsst-web.ncsa.illinois.edu/~buildbot/doxygen/x_masterDoxyDoc/group___l_s_s_t__task__documentation.html as you check it in (and as soon as buildbot notices). Please check that your documentation appears the way that you expected.

 To remind you we need:

1. The Task's purpose
2. How to initialise the Task object
3. How to invoke a Task
4. The config parameters
5. Debugging options enabled with "import debug"
6. A complete example.

...

Think about your users, which includes you!  Please try to make these examples as helpful as possible.

There are example docs in python source code in:

 - python/lsst/meas/algorithms/measurement.py (SourceMeasurementTask)

 - python/lsst/meas/algorithms/detection.py (SourceDetectionTask)

if you're looking for inspiration.  I don't claim that these are the best way to achieve the goal, but let's get the docs written and the haggle over how we should have done it -- i.e. please do it this way for now.

The P1 tasks are:

...

...