DOC: further clarifications to docstring guide

[jorisvandenbossche]

I merged the docstring guide #19704 in its current state from the sprint.

But based on the sprint experience, I think we noticed a few areas that can use further clarifications to have less confusion / discussion:

• Better overview of when to use which type of quotes (single quotes ' or single ` or double backticks ``). The way I currently review:
  • no quotes in type description (even if it may need one according to next rules)
  • single backticks to reference parameter names
  • double backticks for small code snippets, like False or param=value, but, often used class names of pandas like Series, DataFrame, Index are not quoted.
• In specifications like "See Also" or "Returns", include .pandas or not?
• Do we use refer to missing values as "NA", "NaN", "NA/NaN", ..
• Are we OK with using "label" in type descriptions to refer to column names? (instead of str, as this is in principle too restrictive)
• ...

Did you experience any others?

Let's discuss here what to do with them. Detailed inline comments can still be made on #19704

cc @datapythonista @WillAyd @TomAugspurger @jreback

[TomAugspurger]

Your quoting rules seem sensible to me.

For "See Also" I say no to things that are in pandas' top-level namespace, at least Index / Series / DataFrame. Maybe for less well-known things like Categorical.

For Missing values: NA when referring to the concept, NaN (or NaT) when referring to a specific value. So

# docstring for isna.

Check for missing (NA) values. The values ``NaN``, ``NaT``, ... are considered missing.

For "label", yes I think so. Likewise for row labels.

---

Some other ones: Do we use sphinx reference markup in types? I merged a couple in plotting that were like

Returns
--------
ax : :class:`matplotlib.axes.Axes`
    ...

But that's a bit noisy. I think it'd be better to just have

ax : Axes
    The :class:`matplotlib.axes.Axes` this was plotted on...

[TomAugspurger]

We should emphasize linking back to relevant sections of the user guide.

[jorisvandenbossche]

We should emphasize linking back to relevant sections of the user guide.

Yes, I was thinking about if we could have a separate section for this (like See Also now, but then similar box with eg "Related User Guides" or something like that), but that would require some changes to numpydoc to allow this. And I was also thinking of a kind of general way to do this from tagging sections in User guide with methods that should be linked to that section, and then those links could automatically be added in the docstrings (like with a Gallery, the links are also injected into the docstrings).
But since both are rather far off, more plain linking for now is a good recommendation :)

[TomAugspurger]

For now, I think that the extended summary is the best place for referring to the user guide.

[TomAugspurger]

Another quoting rule: exception classes like ValueError.

[IHackPy]

I thought example section too :

1. We should copy our example from normal python terminal instead of IPython or jupyter.
2. When we add comment with in the example and also when therir should gap b/w lines

[TomAugspurger]

In #20332 @adatasetaday mentioned "format of axis parameters".

axis : "{0 or 'index', 1 or 'columns', None}, default None"

To what extent do we think that we can add rules like this to the linter? I'd like as much of this to be rules-based and automated.

[TomAugspurger]

Should explain how we doctest warnings.

doctest doesn't make it show and test when a warning is issued. Our approach
is to include the warning as a comment in the input of the snippet.

def f(x):
    warnings.warn("This function warns")
    return x

So in the doctest, you would write

>>> f(2)
... # UserWarning: This function warns
2

Note that the line displaying the warning starts with `...`. This makes it part of the
input so it isn't actually tested. But it doesn't interfere with the test output.