add_kwargs_to_doc

sherpa.plot.backend_utils.add_kwargs_to_doc(param_doc)

Add documentation for keyword parameters

The plotting functions for each backend take a large number of keyword arguments that are repeated over several methods. This decorator can be used to fill in the description for those keyword arguments into the method docstring to reduce repetition, keep the docstrings readable in the code files, and ensure consistency between different functions.

The decorator uses string formatting and fills all keyword parameters where {kwargs} appears in the docstring. This allows all other parts of the docstring to be written normally.

A typical use case is to define a dictionary of all parameters for a backend, e.g. describe all values that 'color' can take and then pass that same dictionary to the decorator in all methods.

The appropriate number of white space is inserted to generate the numpydoc format, but long lines are not wrapped. Instead, the line wrapping is preserved to maintain special markup (e.g. lists). If lines are very long, they should contain newlines in the param_doc.

Parameters:

param_doc (dict) – Keys in the dictionary are parameters names and values are tuples. The first element of the tuple is the parameters type, the second one the description.

Examples

>>> param_doc = {'c' : ['int', 'thickness of line'],
...              'title' : ['string', 'Title of figure (only use if `overplot=False`)'],
...              'color': ['string or number',
...                  'any matplotlib color with a really long text attached to it that will not fit in one line of text in the docstring']}
>>> @add_kwargs_to_doc(param_doc)
... def test_func2(a, *, title=None, color='None'):
...     """Func that does nothing
...
...     Parameters
...     ----------
...     a : int
...         Our stuff
...     {kwargs}
...     """
...     pass
>>> help(test_func2)
Help on function test_func2 in module sherpa.plot.backend_utils:

test_func2(a, *, title=None, color='None')
    Func that does nothing

    Parameters
    ----------
    a : int
        Our stuff
    title : string, default=None
        Title of figure (only use if `overplot=False`)
    color : string or number, default=None
        any matplotlib color with a really long text attached to it that will not fit in one line of text in the docstring