Skip to content

feat: Option to generate headings (+ ToC entries) for items in summary tables (attributes, functions/methods, classes, modules) #133

Open
@EvieePy

Description

@EvieePy

Description of the bug

When using the Attributes section in a class docstring, E.g.

class Hello:
    """Hello World!
    
    Attributes
    ----------
    thing: int
        The thing for Hello.
    """

Also applies to Google style docstrings.

No ToC of those attributes are generated.
Properties (@property) in the class are properly added to the ToC.

This is also an issue on the insiders build where the use of summaries doesn't include these attributes in it's summary. And without the show_docstring_attributes: false option, the Attributes section is actually generated twice; One with all the properties already included in the ToC and another with all the attributes in the docstring (but they can't be referenced).

Adding doctstring below the attribute works, but this is not ideal, especially when dealing with large documentation or classes with a large amount of attributes or when any ordering of these attributes or logic is needed to be done in __init__.

Full traceback

No traceback.

Expected behavior

The Attributes section from the class docstring displays and add attributes to the toc appropriately and doesn't generate a secondary summary on insiders builds.

Environment information

  • System: Windows-11-10.0.22621-SP0
  • Python: cpython 3.12.0
  • Environment variables:
  • Installed packages:
    • mkdocs v1.5.3
    • mkdocstrings v0.24.0
    • mkdocstrings-python v1.8.0.1.6.1.dev4+g157224d
    • griffe v0.40.1.1.0.0

Metadata

Metadata

Assignees

Labels

featureNew feature or requestinsidersCandidate for Insiders

Type

No type

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions