Help needed with dataclasses and attribute docstring section: duplicate object descriptions

[acgc99]

Hi all,

I'm preparing the documentation for my first public package and I'm facing some issues with Sphinx documentation. This is one the classes that give me problems:

@dataclass
@typechecked
class Material:
    """Class for storing parameters of a material.

    Attributes
    ----------
    atom_number : int
        Atomic number.
    mass_number : float
        Mass number.
    a0 : float, optional
        Lattice parameter in angstrom.
    sia_cutoff : float, optional
        Cutoff distance for interstitial clusters detection, in angstrom.
    vac_cutoff : float, optional
        Cutoff distance for vacancy clusters detection, in angstrom.
    fp_dist : float, optional
        Length of a Frenkel pair, in angstrom.
    density : float, optional
        Atomic density, in atoms/angstrom3.
    ed_min : float, optional
        Minimum displacement energy, in eV.
    ed_avr : float, optional
        Average displacement energy, in eV.
    b_arc : float, optional
        'b' parameter of the arc-dpa fit.
    c_arc : float, optional
        'c' parameter of the arc-dpa fit.
    """
    atom_number: int
    mass_number: float
    a0: float | None = None
    sia_cutoff: float | None = None
    vac_cutoff: float | None = None
    fp_dist: float | None = None
    density: float | None = None
    ed_min: float | None = None
    ed_avr: float | None = None
    b_arc: float | None = None
    c_arc: float | None = None

And I get these warning when I compile the docs:

C:\Users\acgc99\Local\Sync1\Estudios\UA\PhD\Codes\packages\damgen\damgen\materials.py:docstring of damgen.materials.Material.a0:1: WARNING: duplicate object description of damgen.materials.Material.a0, other instance in damgen, use :no-index: for one of them
C:\Users\acgc99\Local\Sync1\Estudios\UA\PhD\Codes\packages\damgen\damgen\materials.py:docstring of damgen.materials.Material.atom_number:1: WARNING: duplicate object description of damgen.materials.Material.atom_number, other instance in damgen, use :no-index: for one of them
C:\Users\acgc99\Local\Sync1\Estudios\UA\PhD\Codes\packages\damgen\damgen\materials.py:docstring of damgen.materials.Material.b_arc:1: WARNING: duplicate object description of damgen.materials.Material.b_arc, other instance in damgen, use :no-index: for one of them
C:\Users\acgc99\Local\Sync1\Estudios\UA\PhD\Codes\packages\damgen\damgen\materials.py:docstring of damgen.materials.Material.c_arc:1: WARNING: duplicate object description of damgen.materials.Material.c_arc, other instance in damgen, use :no-index: for one of them
C:\Users\acgc99\Local\Sync1\Estudios\UA\PhD\Codes\packages\damgen\damgen\materials.py:docstring of damgen.materials.Material.density:1: WARNING: duplicate object description of damgen.materials.Material.density, other instance in damgen, use :no-index: for one of them
C:\Users\acgc99\Local\Sync1\Estudios\UA\PhD\Codes\packages\damgen\damgen\materials.py:docstring of damgen.materials.Material.ed_avr:1: WARNING: duplicate object description of damgen.materials.Material.ed_avr, other instance in damgen, use :no-index: for one of them
C:\Users\acgc99\Local\Sync1\Estudios\UA\PhD\Codes\packages\damgen\damgen\materials.py:docstring of damgen.materials.Material.ed_min:1: WARNING: duplicate object description of damgen.materials.Material.ed_min, other instance in damgen, use :no-index: for one of them
C:\Users\acgc99\Local\Sync1\Estudios\UA\PhD\Codes\packages\damgen\damgen\materials.py:docstring of damgen.materials.Material.fp_dist:1: WARNING: duplicate object description of damgen.materials.Material.fp_dist, other instance in damgen, use :no-index: for one of them
C:\Users\acgc99\Local\Sync1\Estudios\UA\PhD\Codes\packages\damgen\damgen\materials.py:docstring of damgen.materials.Material.mass_number:1: WARNING: duplicate object description of damgen.materials.Material.mass_number, other instance in damgen, use :no-index: for one of them
C:\Users\acgc99\Local\Sync1\Estudios\UA\PhD\Codes\packages\damgen\damgen\materials.py:docstring of damgen.materials.Material.sia_cutoff:1: WARNING: duplicate object description of damgen.materials.Material.sia_cutoff, other instance in damgen, use :no-index: for one of them
C:\Users\acgc99\Local\Sync1\Estudios\UA\PhD\Codes\packages\damgen\damgen\materials.py:docstring of damgen.materials.Material.vac_cutoff:1: WARNING: duplicate object description of damgen.materials.Material.vac_cutoff, other instance in damgen, use :no-index: for one of them

I have more dataclasses with the same issue.

ChatGPT suggested me to use atom_number: int = field(metadata={"doc": "Atomic number."}), but I disagree, since the description might be too long for a single line, and splitting the string into multiple lines will reduce readability.

I would like to use the docstring for documentation and keep dataclass functionalities.

Any suggestion? Thanks!