Dealing with class __slots__

[HealthyPear]

I have a class like this,

class MyClass:
    """
    Summary line.

    Parameters
    ----------
    a: str
        Description of ``a``.
    b: `.SomeType`
        Description of ``b``.
    c: float
        Description of ``c``.
    """

   __slots__ = (
        "a",
        "b",
        "c",
    )

    def __init__(self ,a, b, c):

        self.a = a
        self.b = b
        self.c = c

    # methods after this line

I thought this was sufficient, but I still get warnings like this,

WARNING: [numpydoc] Validation warnings while processing docstring for 'XXX.MyClass.a':
  GL01: Docstring text (summary) should start in the line immediately after the opening quotes (not in the same line, or leaving a blank line in between)
  SS01: No summary found (a short summary in a single line should be present at the beginning of the docstring)

Have I forgotten to do something or is this a bug?

[larsoner]

This is for the docstring of the attribute MyClass.a. You did not add this attribute, so I'm guessing it was added by something automatically (autodoc?). Whatever that automated thing is producing does not seem to have a summary. Have you looked at the output to see what the rendered docstring for MyClass.a looks like?

[HealthyPear]

I see indeed an Attributes Summaryand a Attributes Documentation that must be produced by autodoc (or automodapi in my case - I do .. automodapi:: my_package.my_module where my_module contains MyClass).

I thought numpydoc checks that docstring that I write, does instead check that docstring produced after sphinx extensions have done their job?

[larsoner]

I can't remember the order actually. But based on the behavior here I'm guessing it's after some processing

[HealthyPear]

This seems an easy problem to stumble upon as the class template I show above is quite simple...no one ever reported this?

If it can help, the output of python -m numpydoc my_package.my_module.tank.MyClass with MyClass as above is the following,

Summary line.


:Parameters:

    **a: str**
        Description of `a`.

    **b: float**
        Description of `b`.

    **c: float**
        Description of `c`.












:Attributes:

    **a**
        ..

    **b**
        ..

    **c**
        ..

What I reported above (beginning of the issue) comes from the validation of numpydoc triggered by the sphinx build, whereas this is just the call to the module itself

[HealthyPear]

Sorry, I forgot to say that when using python -m numpydoc --validate I don't get any warning

[HealthyPear]

From your docs I interpret the 2 validation methods as equivalent, so I don't think that numpdoc should validate the docstring resulting from sphinx, but should validate what I feed to sphinx (if this turns out to be the problem).

[HealthyPear]

Another related issue is that if I have a class like that and I add the Notes and Examples section, than I get the warning

GL07: Sections are in the wrong order. Correct order is: Parameters, Attributes, Notes, Examples

and in fact the HTML output shows me that Attributes is added at the end (I see this also from the python module validator)

[HealthyPear]

And yet another missing feature that might be related to this: sometimes I get

GL03:Double line break found; please use only one blank line to separate sections or paragraphs, and do not leave blank lines at the end of docstrings

but I have no idea which line it is exactly and the number would depend on which source numpydoc is actually reading: my source (which is what I would expect), or whatever gets produced by sphinx.

[HealthyPear]

Aha. I maybe found the culprit.

The problem is the use of __slots__ (which I need in my real class, the example here is indeed just a minimal working example for you guys).

Apparently I don't have this problem if I don't use slots and soon after I googled this and found
sphinx-doc/sphinx#4678

[HealthyPear]

Even though I have another class which is not using slots, but that gives me the "wrong section order" warning because I have (in my docstring) only Parameters, Notes and Examples and if I print the resulting docstring from python -m numpydoc I see an :Attributes: section indeed after .. rubric:: Examples.

I don't know if these 2 issues are actually related to the same cause.

[HealthyPear]

Ah no there is some black magic with a metaclass that defines the slots in the __new__ magic/dunder method.

So yes, the issue here is definitely how numpydoc interfaces with __slots__ (or interfaces with sphinx which supports __slots__)

[HealthyPear]

And in particular what happens if the class attributes in __slots__ are also used by the constructor (so they are effectively parameters not only attributes)

[HealthyPear]

Another side-issue: I tried using the dict-style declaration, so

__slots__ = {
        "a": "Description of a",
        "b": "Description of b",
        "c": "Description of c",
    }

and I also get e.g.,

WARNING: [numpydoc] Validation warnings while processing docstring for 'my_package.my_module.MyClass.a':
GL01: Docstring text (summary) should start in the line immediately after the opening quotes (not in the same line, or leaving a blank line in between)