Bug report

Summary

The documentation guide contains a section about docstrings. Unfortunately, in my attempt to add / improve some docstrings I found it largely deficient.

This issue collects the problems I encounted and may serve as a starting point to improve the API docs.

Motivation

A good documentation is essentially for the usability of a library. Even more so, for a large library with many options and making heavy use of *args and **kwargs.

To get improvements here, there has to be a consistent and easily understandable style guide. Otherwise, contributors will not know or bother.

Issues

1. Multiple sources

• the documentation guide
• Numpy: How to document
• The pending Switch to makefile-based doc build. #9513 was pointed out to me as an additional source, however I don't think it says anything about docstrings.
• There are some rules discussed or decided in issues, e.g. Inconsistency between " and ' in the code #8079 on quotes, Set return of type Axes in Numpydoc docstring return type hint for Figure.add_subplot and Figure.add_axes to help jedi introspection #7535, Docstring section "Other Parameters" not rendering with rest of table #6924 on Other Parameters

• Include all information in the docstrings section, reference numpydoc docmentation.

2. Outdated directions

The docstrings section is outdated and thus misleading.

In addition to the “narrative” documentation described above, matplotlib also defines its API reference documentation in docstrings. For the most part, these are standard Python docstrings, but matplotlib also includes some features to better support documenting getters and setters.

better:

In addition to the “narrative” documentation described above, the API reference documentation is generated from docstrings in the code. Generally, matplotlib uses numpy style docstrings [link]. To further enhance the documentation we have augmented numpy style by some additional conventions and features.

Additional Conventions:

Additional Features: [existing stuff here]

• Remove outdated stuff. Add placeholders and notes if there are some known gaps.

3. Additional Conventions

numpydoc does not fully cover all aspects of docstrings. Some should be clarified on the project level.

• Handling of *args and **kwargs: Should they be Parameters, Other Parameters or something else?

• Handling of long lists of value choices:

See here:

projection :
            ['aitoff' | 'hammer' | 'lambert' | 'mollweide' | \
'polar' | 'rectilinear'], optional

• When to use abc, abc, 'abc', "abc", abc. In particular also usage of double or single quotes in the docs (even if it's: Do as you like but don't change existing stuff). Indicate if these decisions deviate intentionally from other sources you link (e.g. numpy: "Variable, module, function, and class names should be written between single back-ticks (numpy)", vs Formatting: "Function arguments and keywords should be referred to using the emphasis role."

• When to cross reference and when not "Types don't need to be marked up." vs "Sometimes sphinx doesn't automatically put in links with out the markup though." See here Also if sphinx has a bug that return values are not always cross-referenced, mention that and your policy (Either keep plain types, it will be fine once sphinx is fixed. Or add reference now, we can strip it later).

• Usage of call signature: Some methods have this, others not.

    Call signature::

      text(x, y, s, fontdict=None, **kwargs)

4. Migration of documentation

• State that there's still a mixture of old and new styles and that the migration is ongoing.
• List deprecated conventions and how to replace them.

5. Examples

• Add examples in the above parts as much as possible. They are more instructure than lengthy texts.
• Link to parts of code with good documentation, from which one can learn.