Use docstrings to display help in beast/main.py

[lea-hagen]

As discussed in #603, using the beast [function] interface doesn't show much information in its help message. Here's an example for plot_cmd:

• Using the function's argparse interface:

> python -m beast.plotting.plot_cmd -h
usage: plot_cmd.py [-h]
                   [-s {png,jpg,jpeg,pdf,ps,eps,rgba,svg,tiff,tif,pgf,svgz,raw}]
                   [-t] [--mag1 MAG1] [--mag2 MAG2] [--mag3 MAG3]
                   filename

positional arguments:
  filename              Path to FITS file to plot

optional arguments:
  -h, --help            show this help message and exit
  -s {png,jpg,jpeg,pdf,ps,eps,rgba,svg,tiff,tif,pgf,svgz,raw}, --savefig {png,jpg,jpeg,pdf,ps,eps,rgba,svg,tiff,tif,pgf,svgz,raw}
                        Save figure to a file of specified type rather than
                        show it. Must be one of: "png", "jpg", "jpeg", "pdf",
                        "ps", "eps", "rgba", "svg", "tiff", "tif", "pgf",
                        "svgz", "raw"
  -t, --tex             Configure Matplotlib to use LaTeX; sets rcParam
                        "usetex" to True. (Requires working TeX installation.)
                        Defaults to false.
  --mag1 MAG1           Choose filter for mag1 (color=mag1-mag2)
  --mag2 MAG2           Choose filter for mag2 (color=mag1-mag2)
  --mag3 MAG3           Choose filter for the magnitude

• Using the beast interface, which just grabs the input parameter names from the function:

> beast plot_cmd -h
usage: beast plot_cmd [-h] [--mag1_filter MAG1_FILTER]
                      [--mag2_filter MAG2_FILTER] [--mag3_filter MAG3_FILTER]
                      [--savefig SAVEFIG] [--show_plot SHOW_PLOT]
                      fitsfile

positional arguments:
  fitsfile

optional arguments:
  -h, --help            show this help message and exit
  --mag1_filter MAG1_FILTER
  --mag2_filter MAG2_FILTER
  --mag3_filter MAG3_FILTER
  --savefig SAVEFIG
  --show_plot SHOW_PLOT

From some quick googling, I found at least one way to get docstrings from a function. So if we make sure those are standardized, we should be able to write a quick function to parse them into a useful help message.

>>> from beast.plotting import plot_cmd
>>> plot_cmd.plot_cmd.__doc__.split('\n')
['',
 '    Read in flux from real or simulated data in fitsfile and plot a',
 '    color-magnitude diagram based on specified filters.',
 '',
 '    Parameters',
 '    ----------',
 '    fitsfile : str',
 '        input fitsfile (includes full path to file); format = .fits',
 "    mag1_filter : str (default='F475W')",
 '        1st color filter',
 "    mag2_filter : str (default='F814W')",
 '        2nd color filter',
 "    mag3_filter : str (default='F475W')",
 '        magnitude',
 '    savefig : str (default=False)',
 "        to save the figure, set this to the file extension (e.g., 'png', 'pdf')",
 '    show_plot : boolean',
 '        True, show the plot (to screen or a file)',
 '        False, return the fig',
 '    ']

[s-goldman]

This seems to be an issue of having different help formatting for the initial parser (-h) and the subparsers (e.g. plot_cmd -h).

For beast -h we want: parser = argparse.ArgumentParser(formatter_class=argparse.RawDescriptionHelpFormatter)

For beast plot_cmd -h we want: subparsers = parser.add_subparsers(formatter_class=argparse. RawTextHelpFormatter)

The problem is that changing the subparsers format only changes the help formatting for beast -h.

Looking online it also seems that to create different help formatting for difference arguments requires custom functions, with no real easy catch-all function that I can find.