feature: Warn about attributes sections found in __init__ method docstrings

[CunliangGeng]

Description of the bug

If attributes are documented in the __init__ method (see class below), their types are missing after rendering (see the screenshot).

class MolecularFamily:
    def __init__(self, family_id: str):
        """Class to model molecular family.

        Args:
            family_id: Unique id for the molecular family.

        Attributes:
            family_id: Unique id for the molecular family.
            spectra_ids: Set of spectrum ids in the molecular family.
        """
        self.family_id: str = family_id
        self.spectra_ids: set[str] = set()
        self._spectra: set[Spectrum] = set()
        self._strains: StrainCollection = StrainCollection()

screenshot

To Reproduce

WRITE MRE / INSTRUCTIONS HERE

Full traceback

Full traceback

PASTE TRACEBACK HERE

Expected behavior

Not matter where attributes are documented (module level, class level or __init__ method), their types should be extracted and rendered properly.

Environment information

python -m mkdocstrings_handlers.python.debug  # | xclip -selection clipboard

• System: macOS-14.4.1-arm64-arm-64bit
• Python: cpython 3.9.18
• Environment variables:
• Installed packages:
  • mkdocs v1.5.3
  • mkdocstrings v0.24.1
  • mkdocstrings-python v1.9.0
  • griffe v0.42.0

Additional context

mkdocs.yml

plugins
- mkdocstrings:
    handlers:
      python:
        options:
          members_order: source
          filters: ["!^_"]
          merge_init_into_class: true
          show_if_no_docstring: true
          show_root_heading: true
          show_root_full_path: false
          show_signature_annotations: true
          signature_crossrefs: true
          separate_signature: true
          show_symbol_type_heading: true
          show_symbol_type_toc: true

Boost priority

• Boost priority in our backlog through Polar.sh. Higher pledge, higher priority.
• Minimum pledge by user/organization is $5, minimum amount for boost is $30.
• View all issues with pledges.
• We receive the funds once the issue is completed and confirmed by you.
• Features with the insiders label are released to sponsors first, and tied to a funding goal.

[pawamoy]

Hello, thanks for the report!

Attributes section only make sense in module and class docstrings. An __init__ method doesn't have any attributes, and Griffe doesn't look into the parent class to find their types. We could consider supporting that, but IMO we already have one obvious solution. Napoleon docs do not show examples of an Attributes section in an __init__ method docstring either, so I'm inclined to stick to the current behavior 🙂

class MolecularFamily:
    """Class to model molecular family.

    Attributes:
        family_id: Unique id for the molecular family.
        spectra_ids: Set of spectrum ids in the molecular family.
    """

    def __init__(self, family_id: str):
        """Initialize the molecular family.

        Args:
            family_id: Unique id for the molecular family.
        """
        self.family_id: str = family_id
        self.spectra_ids: set[str] = set()
        self._spectra: set[Spectrum] = set()
        self._strains: StrainCollection = StrainCollection()

I'll close this but feel free to comment further! Maybe I'm missing something here.

[pawamoy]

Actually I'll reopen, as we could maybe emit a warning when we find an attributes section in an __init__ method docstring 🙂

[CunliangGeng]

Thanks for the explanation! It's nice to emit a warning.