Inherited attributes do not get the attribute docstring from parent class

[osamimi]

I am using pydantic + google style doc strings.

It looks like this extension expects the fields to be documented under a 'Parameters:' section in the class docstring, not 'Attributes:' which threw me off for a bit.

If I do that the table produced by the extension is correct (shows the docstring). However,

• the docstring doesn't show up under the separate attribute heading (ParentClass.attr2) that shows up in the ToC.
• the docstring doesn't show up in the Parameters table of the inherited classes (ChildClass.attr2).

If I list the docstring right under the attribute itself, like attr1 in the example, it shows up in both the parent and child class, both in the 'summary' attributes table and under the attribute headings.

Example code:

class ParentClass(_FrozenDataClass, frozen=True):
    """ParentClass

    Parameters:
        attr2: attr2 docstring

    """

    attr1: int
    """attr1 docstring"""

    attr2: float = 1.0


class ChildClass(ParentClass):
    """ChildClass"""
    pass

My mkdocs.yml below. Note that I have griffe_inherited_docstrings, griffe_fieldz: {include_inherited: true}, inherited_members: true (not sure what each one does...).

Supporting individual docstrings per field in this extension would indirectly solve the problem, but I also do wonder why when using 'Parameters:', child classes don't inherit the attribute docstrings.

  - mkdocstrings:
      handlers:
        python:
          paths: src/filtpy
          import:
            - url: https://docs.python.org/3/objects.inv
              domains: [py, std]
          options:
            extensions:
              - griffe_inherited_docstrings
              - griffe_fieldz: {include_inherited: true}
              # - griffe_pydantic: {schema: false}
            members_order: "source"
            show_source : true
            show_bases : true
            parameter_headings: false
            summary:
                attributes: true
                functions: true
                modules: true
                classes: true
            show_symbol_type_heading : true
            show_category_heading: false
            docstring_style : "google"
            docstring_section_style : "table"
            show_if_no_docstring : true # FIXME: change to false
            signature_crossrefs : true
            show_signature: true
            show_signature_annotations : true
            show_root_heading: false
            merge_init_into_class: true
            show_root_full_path: true
            show_root_members_full_path: false
            show_object_full_path: false
            show_symbol_type_toc: true
            separate_signature: true
            heading_level: 2
            inherited_members: true

[tlambert03]

thanks @osamimi all helpful.

It looks like this extension expects the fields to be documented under a 'Parameters:' section in the class docstring, not 'Attributes:' which threw me off for a bit.

this plugin doesn't specifically expect anything explicitly (yet). Though there are definitely rough edges where I may not have anticipated and handled common patterns well. griffe does the parsing, both of the docstrings and the attributes, and assigns various members as attributes and/or parameters according to a "conventional" (non-dataclass-like) pattern.

The goal of this plugin (which is admittedly/clearly still rough around the edges) is to unify that model with the various ways that people express dataclass-like stuff. Certainly, we need to do some work on merging parameters/attributes, which tend to be the same thing in a dataclass.

All that to say, thanks for this very helpful info. please give me a couple days to have a closer look. I think it's all hovering around the same general concept of how we merge all these different ways that people express fields and their descriptions.