ctools

I’m putting this for 1.0 ... having an easy way to print the help and list the parameters for each command line tool is very important in day-to-day usage.

I think `ctlike --help` is best ... that’s how all Unix tools work.

`cshelp ctlike` would be nice too ... I could implement this and also add an option so the user can list all tools and which version of the software is installed.

The FTOOLS way would be to call `fhelp` or `fthelp`, which I think sometimes opens up a txt file in the console and sometimes an html file in the browser.

Jürgen, how do you want to do this for ctools?
I could work on this this week.

Decided to use rst files on input, convert them into plain text files and install them in shared area.

Implement in GApplication the --help (and/or -h) option.

I’ve written a python script (see attached) that should clean up rst files for easier human readability. I tested it on the ones in $CTOOLS/doc/source/reference_manual, and it works pretty well. See the result:

.. _ctlike:

ctlike
======

Performs binned and unbinned maximum likelihood analysis of CTA data.

Synopsis
--------

Determines source model parameters, such as flux, spectral index, source 
position, and source extent from a maximum likelihood analysis of CTA data.
The analysis can be done in a binned or an unbinned formulation of the
log-likelihood function.
For binned analysis, a counts cube produced by :doc:`ctbin` is required.
For unbinned analysis, an event list processed by :doc:`ctselect` is required.
Based on the input file format, ctlike automatically selects between binned
and unbinned maximum likelihood analysis.

General parameters
------------------

``inobs [file]``
    Input event list, counts cube or observation definition XML file.

``inmodel [string]``
    Source model input XML file.

``expcube [file]``
    Exposure cube file (only needed for stacked analysis).

``psfcube [file]``
    PSF cube file (only needed for stacked analysis).

``bkgcube [file]``
    Background cube file (only needed for stacked analysis).

``caldb [string]``
    Calibration database.

``irf [string]``
    Instrument response function.

``outmodel [string]``
    Source model result XML file with values and uncertainties updated by
    the maximum likelihood fit.

``(stat = POISSON) [string]``
    Fitting statistics (POISSON or GAUSSIAN; only affects binned analysis).

``(edisp = no) [boolean]``
    Applies energy dispersion to response computation.

``(refit = no) [boolean]``
    Performs refitting of solution after initial fit.

Standard parameters
-------------------

``(chatter = 2) [integer]``
    Verbosity of the executable:
     chatter = 0: no information will be logged

     chatter = 1: only errors will be logged

     chatter = 2: errors and actions will be logged

     chatter = 3: report about the task execution

     chatter = 4: detailed report about the task execution

``(clobber = yes) [boolean]``
    Specifies whether an existing output counts cube should be overwritten.

``(debug = no) [boolean]``
    Enables debug mode. In debug mode the executable will dump any log file output to the console.

``(mode = ql) [string]``
    Mode of automatic parameters (default is "ql", i.e. "query and learn").

``(logfile = ctlike.log) [string]``
    Name of log file.

Related tools
-------------

None

After:

ctlike
======

Performs binned and unbinned maximum likelihood analysis of CTA data.

Synopsis
--------

Determines source model parameters, such as flux, spectral index, source 
position, and source extent from a maximum likelihood analysis of CTA data.
The analysis can be done in a binned or an unbinned formulation of the
log-likelihood function.
For binned analysis, a counts cube produced by :doc:`ctbin` is required.
For unbinned analysis, an event list processed by :doc:`ctselect` is required.
Based on the input file format, ctlike automatically selects between binned
and unbinned maximum likelihood analysis.

General parameters
------------------

inobs [file]
    Input event list, counts cube or observation definition XML file.

inmodel [string]
    Source model input XML file.

expcube [file]
    Exposure cube file (only needed for stacked analysis).

psfcube [file]
    PSF cube file (only needed for stacked analysis).

bkgcube [file]
    Background cube file (only needed for stacked analysis).

caldb [string]
    Calibration database.

irf [string]
    Instrument response function.

outmodel [string]
    Source model result XML file with values and uncertainties updated by
    the maximum likelihood fit.

(stat = POISSON) [string]
    Fitting statistics (POISSON or GAUSSIAN; only affects binned analysis).

(edisp = no) [boolean]
    Applies energy dispersion to response computation.

(refit = no) [boolean]
    Performs refitting of solution after initial fit.

Standard parameters
-------------------

(chatter = 2) [integer]
    Verbosity of the executable:
     chatter = 0: no information will be logged

     chatter = 1: only errors will be logged

     chatter = 2: errors and actions will be logged

     chatter = 3: report about the task execution

     chatter = 4: detailed report about the task execution

(clobber = yes) [boolean]
    Specifies whether an existing output counts cube should be overwritten.

(debug = no) [boolean]
    Enables debug mode. In debug mode the executable will dump any log file output to the console.

(mode = ql) [string]
    Mode of automatic parameters (default is "ql", i.e. "query and learn").

(logfile = ctlike.log) [string]
    Name of log file.

Related tools
-------------

None

Usage:

$ clean.rst.file.py input_filename output_filename

I added a need_help() method to GApplication that catches the --help option that is specified on the command line (it is for the moment assumed that --help is the only option that is specified on the command line).

On the ctools side, I added some code to the ctool base class that handles the case that the need_help() returns true (i.e. that the --help option has been specified on the command line). Help files named <tool>.txt and installed in $CTOOLS/share/help will be displayed to the console.

I added a target to the Makefile that generates the <tool>.txt files for all tools and scripts from the .rst files during the install process. I reimplemented clean.rst.file.py using sed so that the file translation is directly done at the Makefile level without requiring an external Python script.

The code is ready to go into devel.

Merged into devel.