Inconsistent handling of class attributes in docs and missing attribute descriptions

[grossardt]

I noticed that class attributes are not documented very well, take e.g. FermionicOp:

• num_spin_orbitals is listed in the class docstring under an Attributes: header. In the html docs this is then displayed directly under the previous headline 'Iteration' without any indication that this is now a listing of attributes.
• further down in the docs there is a section 'Attributes' that lists atol, rtol, and register_length which seem to be gathered by Sphinx from the @property decorated methods of the parent classes. However, the docstrings of these attributes are not shown.

I am not completely sure if this is a bug or somehow intentional. Also not sure if it can just be fixed via the Sphinx configuration, but my feeling is that the docstrings themselves should be amended?

Comparing with the qiskit docs, attributes typically seem to be defined directly after the class docstring with a type declaration and followed by their docstring (and mostly without assigning a value), e.g. for the FermionicOp we would have something like:

class FermionicOp(SparseLabelOp):
    r"""N-mode Fermionic operator.
    ...
    """

    num_spin_orbitals: int
    """The number of spin orbitals"""

    atol: float
    """Absolute numerical tolerance used by the class methods"""

[mrossinek]

Thanks for pointing this out! Indeed, the handling of @property attributes and publicly directly accessible attributes is a bit inconsistent, especially when it comes to how they are displayed in the docs. In the past, we used to only have @property attributes but over the past few releases we have started using pubic attributes directly, if the @property getter/setter methods are trivial.

What you see now, is likely also different to before, because the Sphinx theme which we use for our docs has been changed significantly. I will bring this issue to the team's attention who is working on the theme because I believe they would be interested in improving this :+1: