"Attributes" in Numpy-style class docstrings are parsed as Parameters

[janfreyberg]

Numpy docstrings for classes have an Attributes section:

https://numpydoc.readthedocs.io/en/latest/format.html#class-docstring

However, if I parse a docstring that adheres to it, the Attributes are listed as Parameters:

from docstring_parser import parse, Style

docstring = """Test class

My test class does nothing

Attributes
----------
data : None
  An empty field
"""

parsed_docstring = parse(d, style=Style.numpydoc)

for param in parsed_docstring.params:
    print(param.arg_name)

# outputs:
# 'data'

[rr-]

@thekrampus would it be okay with you to separate these completely or do we need to maintain backwards compat here?

[thekrampus]

@rr- there's no reason we can't separate them.

[thekrampus]

Numpydoc docstrings also have an "Receives" section for values received by generators, as well as an "Other Parameters" section for seldom-used parameters. The parser uses DocstringParam for both of these as well as for attributes and ordinary parameters.

Likewise, DocstringReturns is also used for yields, and DocstringRaises is also used for warns. If we want to make distinctions, there are a few ways of going about it:

1. Make distinct DocstringMeta subclasses for each
2. Keep the existing DocstringMeta subclasses and use the meta args to make the distinction
3. Add some attribute to the existing DocstringMeta subclasses that distinguishes the variant, like DocstringParam.is_generator does now

I favor 2.

[rr-]

1. Make distinct DocstringMeta subclasses for each
2. Keep the existing DocstringMeta subclasses and use the meta args to make the distinction
3. Add some attribute to the existing DocstringMeta subclasses that distinguishes the variant, like DocstringParam.is_generator does now

I understand 1. and 3. but I don't understand 2. could you please elaborate more? For now I'm in favor of 3

[thekrampus]

I'm talking about using DocstringMeta.args to distinguish between parameters/attributes/whatever. In other words, rewrite Docstring.params as something like:

@property
def params(self) -> T.List[DocstringParam]:
    return [item for item in self.meta if 'param' in item.args]

and so on for attributes, raises, returns, yields, etc

I'm not sure what the intended use of args is -- seems like they correspond to ReST structural elements, but the google and numpydoc parsers still populate them manually.