I don't understand the comment about structuring the docs. My page on how to do this (https://confluence.lsstcorp.org/display/DM/How+to+document+a+Task) requests the order:

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.

and that's pretty much what you propose in your example, although you omitted the sections on Initialisation and Invoking. If you don't like my proposal file an RFC, but please don't a) fail to follow the instructions, or b) tell other people to do the same.

For a compliant Task, see
https://lsst-web.ncsa.illinois.edu/doxygen/x_masterDoxyDoc/classlsst_1_1meas_1_1algorithms_1_1detection_1_1_source_detection_task.html#SourceDetectionTask_

I was not recommending anything against the rules. Robert Lupton If you had looked at the served documentation you would have seen the issue. Many of the early tasks had the debugging information separated into two subsections with the example separating them. The second section was boilerplate that we moved elsewhere. Your example task does it the way I recommended: omitting the second debugging boilerplate and providing a link, instead.

Your comment was:

Yes Robert Lupton's original template separated them, with the example in the middle, but that makes the debug info very hard to use. This also centralizes boilerplate.

If this refers to old email it's unhelpful; if it refers to the confluence page I didn't understand what you meant and asked for clarification.

The rule you didn't follow was to include sections on Initialisation and Invoking in your example.

Robert, there are sections on Initialization and Invoking in this example. They are called "Task initialization" and "Inputs/Outputs to the run method." Is that the issue?

Please look at the doc as linked to my working directory and please let me know what is missing. I'm going to merge this today:

http://lsst-web.ncsa.illinois.edu/~yusra/ip_isr_doc/classlsst_1_1ip_1_1isr_1_1isr_task_1_1_isr_task.html

Russell, thank you for super-fast turnaround and helpful comments.
I addressed all of them. Re: the display flag, I looked at other examples and saw that --ds9 was the most commonly used flag used to display the results in example tasks. I changed --displayResult to --ds9, and instead of suggesting it in the example call, I showed the three optional flags available on runIsrTask.py explicitly.
Merged to master