Numpy docstring format#

Numpy docstring format:This format divides the docstring into clear sections, each havingdifferent parsing rules that make the docstring easy to read both asraw text and as HTML. We could consider alternatives, or invent ourown, but this is a strong choice, as it's well used and understood inthe Numpy/Scipy community.

Cross references#

Most of the docstrings in matplotlib use explicit "roles" when linkingto other items, for example::func:`myfunction`. As of Sphinx0.4, there is a "default_role" that can be set to "obj", which willpolymorphically link to a Python object of any type. This allows oneto write`myfunction` instead. This makes docstrings much easierto read and edit as raw text. Additionally, Sphinx allows for settinga current module, so links like`~matplotlib.axes.Axes.set_xlim`could be written as`~axes.Axes.set_xlim`.

Overriding signatures#

Many methods in matplotlib use the*args and**kwargs syntaxto dynamically handle the keyword arguments that are accepted by thefunction, or to delegate on to another function. This, however, isoften not useful as a signature in the documentation. For thisreason, many matplotlib methods include something like:

defannotate(self,*args,**kwargs):"""    Create an annotation: a piece of text referring to a data    point.    Call signature::      annotate(s, xy, xytext=None, xycoords='data',               textcoords='data', arrowprops=None, **kwargs)    """

This can't be parsed by Sphinx, and is rather verbose in raw text. Asof Sphinx 1.1, if theautodoc_docstring_signature config value isset to True, Sphinx will extract a replacement signature from thefirst line of the docstring, allowing this:

defannotate(self,*args,**kwargs):"""    annotate(s, xy, xytext=None, xycoords='data',               textcoords='data', arrowprops=None, **kwargs)    Create an annotation: a piece of text referring to a data    point.    """

The explicit signature will replace the actual Python one in thegenerated documentation.

Linking rather than duplicating#

Many of the docstrings include long lists of accepted keywords byinterpolating things into the docstring at load time. This makes thedocstrings very long. Also, since these tables are the same acrossmany docstrings, it inserts a lot of redundant information in the docs-- particularly a problem in the printed version.

These tables should be moved to docstrings on functions whose onlypurpose is for help. The docstrings that refer to these tables shouldlink to them, rather than including them verbatim.

autosummary extension#

The Sphinx autosummary extension should be used to generate summarytables, that link to separate pages of documentation. Some classesthat have many methods (e.g.Axes) should be documented withone method per page, whereas smaller classes should have all of theirmethods together.

Examples linking to relevant documentation#

The examples, while helpful at illustrating how to use a feature, donot link back to the relevant docstrings. This could be addressed byadding module-level docstrings to the examples, and then includingthat docstring in the parsed content on the example page. Thesedocstrings could easily include references to any other part of thedocumentation.

Documentation using help() vs. a browser#

Using Sphinx markup in the source allows for good-looking docs in yourbrowser, but the markup also makes the raw text returned using help()look terrible. One of the aims of improving the docstrings should beto make both methods of accessing the docs look good.