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"""