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.