Generalize doc style for class attributes

[pkausw]

Currently, we have an inconsistent style of how we document class attributes. Here are the options:

1. no documentation whatsoever --> this needs to be fixed
2. document the class attribute in the rst-stlye doc string of the class, e.g. in columnflow.ml.MLModel

class my_class(objects):
"""
    .. py:classattribute:: my_attribute

        This is a nice description
"""
    my_attribute = "foo"

3. document it as just an attribute in the same manor, e.g. in columnflow.util.TaskArrayFunction

class my_class(objects):
"""
    .. py:attribute:: my_attribute

        This is a nice description
"""
    my_attribute = "foo"

4. document the attribute directly in the code, like this

class my_class(objects):
"""
   Some unrelated doc string
"""
    my_attribute = "foo"
    """This is a nice description"""

I suggest to generalize the style in our docs. In principle, we could do style 2 or 3, but this has the disadvantage that the autodoc extension in sphinx doesn't pick it up correctly. As a result, the summary table with all the attributes has an empty column (see [1]) and is both in the doc string of the class itself as well as in the member list [2]. Here, we could of course opt to not show all members and only use the description in the doc string.

On the other hand, we could also use style 4, which works nicely with the autodoc extension. For example, the code

    single_config = False
    """default setting mark whether this model accepts only a single config

    :type: bool

    The default flag that marks whether this model only accepts a single config object in case
    no value is passed in the constructor. Converted into an instance attribute upon
    instantiation.
    """

will result in display [3] and [4]. In my personal opinion, the main advantage of option 4 w.r.t. 2+3 is that this will make the docs more maintainable since e.g. the default value is extracted directly from the code.
Additionally, the decision which members to show isn't hardcoded in some doc string, but can be centerally configured in the sphinx config or the corresponding .rst files for the individual pages.

This should be discussed of course, so any feedback would be most welcome!

[1]

[2]

[3]

[4]