René's URL Explorer Experiment

{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"CHANGE FEATURE: Allow a custom template RST for plot methods","articleBody":"#### Summary\r\nPlot methods should be documented using a template rather than a hard-coded docstring.\r\n\r\n#### Reason\r\nYou could easily add more examples and explanation\r\n\r\n#### Current behaviour\r\nPlot 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`\r\nparameter.\r\n\r\n#### New behaviour\r\nInstead 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.\r\n\r\nThose 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)``\r\n\r\n#### Examples\r\nDefault template for the main docstring\r\n\u003cdetails\u003e\r\n\r\n```reStructuredText\r\n{summary}\r\n\r\n{description}\r\n\r\nTo plot data from a netCDF file type::\r\n\r\n    \u003e\u003e\u003e psy.plot.{identifier}({example_call})\r\n```\r\n\u003c/details\u003e\r\n\r\n***\r\n\r\nDefault template for the epilog\r\n\u003cdetails\u003e\r\n\r\n```reStructuredText\r\nExamples\r\n--------\r\nTo explore the formatoptions and their documentations, use the\r\n``keys``, ``summaries`` and ``docs`` methods. For example::\r\n\r\n    \u003e\u003e\u003e import psyplot.project as psy\r\n\r\n    # show the keys corresponding to a group or multiple\r\n    # formatopions\r\n    \u003e\u003e\u003e psy.plot.{identifier}.keys('labels')\r\n\r\n    # show the summaries of a group of formatoptions or of a\r\n    # formatoption\r\n    \u003e\u003e\u003e psy.plot.{identifier}.summaries('title')\r\n\r\n    # show the full documentation\r\n    \u003e\u003e\u003e psy.plot.{identifier}.docs('plot')\r\n\r\n    # or access the documentation via the attribute\r\n    \u003e\u003e\u003e psy.plot.%(identifier)s.plot\r\n```\r\n\u003c/details\u003e\r\n\r\n***\r\n\r\nNew function call for `ProjectPlotter._register_plotter`\r\n\r\n\u003cdetails\u003e\r\n\r\n```python\r\ndef _register_plotter(cls, identifier, module, plotter_name,\r\n                      plotter_cls=None, summary='', prefer_list=False,\r\n                      default_slice=None, default_dims={},\r\n                      example_call=\"filename, name=['my_variable'], ...\",\r\n                      description_template='description.rst',\r\n                      epilog_template='epilog.rst',\r\n                      plugin=None):\r\n                      \"\"\"show_examples should be depreceated\"\"\"\r\n```\r\n\u003c/details\u003e\r\n","author":{"url":"https://github.com/Chilipp","@type":"Person","name":"Chilipp"},"datePublished":"2018-04-12T20:58:02.000Z","interactionStatistic":{"@type":"InteractionCounter","interactionType":"https://schema.org/CommentAction","userInteractionCount":0},"url":"https://github.com/5/psyplot/issues/5"}