psyplot
CHANGE FEATURE: Allow a custom template RST for plot methods
Summary
Plot methods should be documented using a template rather than a hard-coded docstring.
Reason
You could easily add more examples and explanation
Current behaviour
Plot methods are registered using psyplot.project.register_plotter and the documentation is generated via the psyplot.project.ProjectPlotter._gen_doc method. This only gives a minimal possibility to modify the plot method, you can only set the example_call and the show_examples
parameter.
New behaviour
Instead of hard-coded keywords, such as example_call and show_examples, one should create a template for the description and another template for the epilog.
Those templates could then be specified in the register_plotter call and the psyplot.project.ProjectPlotter._register_plotter method takes **kwargs that are than used to format the template via template_str.format(**kwargs)
Examples
Default template for the main docstring
{summary}
{description}
To plot data from a netCDF file type::
>>> psy.plot.{identifier}({example_call})
Default template for the epilog
Examples
--------
To explore the formatoptions and their documentations, use the
``keys``, ``summaries`` and ``docs`` methods. For example::
>>> import psyplot.project as psy
# show the keys corresponding to a group or multiple
# formatopions
>>> psy.plot.{identifier}.keys('labels')
# show the summaries of a group of formatoptions or of a
# formatoption
>>> psy.plot.{identifier}.summaries('title')
# show the full documentation
>>> psy.plot.{identifier}.docs('plot')
# or access the documentation via the attribute
>>> psy.plot.%(identifier)s.plot
New function call for ProjectPlotter._register_plotter
def _register_plotter(cls, identifier, module, plotter_name,
plotter_cls=None, summary='', prefer_list=False,
default_slice=None, default_dims={},
example_call="filename, name=['my_variable'], ...",
description_template='description.rst',
epilog_template='epilog.rst',
plugin=None):
"""show_examples should be depreceated"""