Docs: Moved Attribute Docs Out of Docstring

[MattBuckley-TfN]

Describe Changes

Moved attributes docs to the attribute themselves instead of in the class docstring. Also, removed type annotations from LogHelper docstring as they exist in the signature.

Task Checklist

• [x] Have unittests been added (testing individual functions and their edge cases) - NA
• [x] Have integration tests been added (if applicable, to test modules of functionality) - NA
• [x] Have new dependencies been added to either requirements.txt, requirements_dev.txt, or docs/requirements.txt? - NA

---

📚 Documentation preview 📚: https://caftoolkit--158.org.readthedocs.build/en/158/

[MattBuckley-TfN]

Noticed an issue with documenting dataclasses (I have confirmed it happens with either pydantic or built-in dataclasses) where the class parameters are automatically added to the docstring.

This causes problems with autosummary because it places the parameters section after the methods and attributes tables but before the attributes docmentation (see image)

This can be somewhat "fixed" by documenting the attributes and methods outside the class, although this separates the attributes so they now use their full names and it doesn't look as neat and we can't enable this for dataclasses but use the other method elsewhere.

I don't think the parameters section actually provides any useful information as the parameters are already covered in the Attributes section so I think the preference would be to stick with the current way autosummary displays things and try to remove the additional parameters section that dataclasses seem to add.

I've attached all the different HTML files in this zip archive. ToolDetails docs options.zip

[MattBuckley-TfN]

Found a workaround which I think is fairly simple, if we add a parameters section to the class docstring then it places it in the correct location and we can just add links to the attributes which contain more information. Docstring looks like this:

@dataclasses.dataclass
class ToolDetails:
    """Information about the current tool.

    Parameters
    ----------
    name
        See :any:`name`.
    version
        See :any:`version`.
    homepage
        See :any:`homepage`.
    source_url
        See :any:`source_url`.
    """

HTML output looks like:

[BenTaylor-TfN]

Summarising the discussion from earlier today.

Problems

• Although numpydoc (the standard we follow) states we should document attributes as part of the doc string, these are not picked up correctly by sphinx.
• We also noted that dataclases are an edge case here as you don't write an __init__() function.

Solutions

• The __init__() function should never be documented directly. The docstring for this function instead belongs in the class docstring.
• Attributes that are properties should be documented as their property function
• Other attributes should have a docstring added directly below their definition. See Example below

Example

Class ExampleClass:
    """An example class.

    A longer description of this class that can go across
    multiple lines.

    Parameters
    ----------
    param1:
        The first parameter to the constructor.
    """"

    a_class_attribute = 100
    """Class attributes should be documented underneath, like this"""

    def __init__(param1: float):
        self.param1 = param1
        """Attributes can also be documented inside the __init__."""

[MattBuckley-TfN]

Are we happy for these changes to be merged as is?