spine.utils.docstring

Docstring inheritance utilities.

Functions

merge_ancestor_docstrings(cls)

Automatically merge Attributes sections from parent class docstrings.

spine.utils.docstring.merge_ancestor_docstrings(cls)

Automatically merge Attributes sections from parent class docstrings.

This function extracts the Attributes section from all direct parent classes and prepends them to the child class’s Attributes section. This is designed to work with numpy-style docstrings.

The function only looks at direct parent classes (cls.__bases__) rather than the full MRO to avoid duplicate attributes when multiple levels of inheritance are involved.

Parameters:

cls (type) – The class whose docstring should be updated with parent attributes

Notes

This function modifies the class’s __doc__ attribute in-place. It is typically called from __init_subclass__ hooks in base classes to automatically merge docstrings for all subclasses.

The function looks for the “Attributes” section in numpy-style docstrings, which is formatted as:

Attributes:

attribute_nametype

Description

.. rubric:: Examples

>>> class Parent:

… ‘’’Parent class.

…

… Attributes

… ———-

… xint

… Parent attribute

… ‘’’

… def __init_subclass__(cls, **kwargs):

… super().__init_subclass__(**kwargs)

… merge_ancestor_docstrings(cls)

…

>>> class Child(Parent):

… ‘’’Child class.

…

… Attributes

… ———-

… yint

… Child attribute

… ‘’’

>>> # Child.__doc__ now contains both x and y in Attributes section