Filtering attributes with members does not work as advertised

[hamelsmu]

The docs state that members can be used to filter attributes

But this is not the case. values for the members field only seem to filter methods, and all attributes are shown. In fact, I don't think there is a way to filter attributes in the config?

[machow]

It seems like there may be two forces at play here:

• If a class has an Attributes section of its docstring, then it gets rendered
• objects like classes and modules can also have individual attributes documented, similar to documenting methods.
  • in this case, members should let you filter what gets documented

I wonder what should happen in the case where an Attributes section exists AND members is specified? In any event, it makes sense that this behavior is confusing. I can take a quick look at how other tools handle this tomorrow....

[machow]

It looks like mkdocstrings (which is super great) just renders everything, if you have it:

• an Attributes section in your docstring
• individual attribute member docs (specified by the members option).
  • these are automatically included if members is unspecified, and the attribute has a docstring

I can tee up work to do the same thing (so that metaflow.Current attributes will get automatically documented). I wonder if, once it's in place, that will reduce the confusion of trying to filter an Attributes section. I can see how documenting attributes 2 ways has the potential to create a lot of confusion.

mkdocstring example

Here's a fairly involved example.

class SomeClass:
    """Some cool class

    Parameters
    ----------
    c:
        woah man

    Attributes
    ----------
    a:
        The a attribute
    b:
        The b attribute
    """

    a: int
    b: int
    """Another thing."""


    def __init__(self, c: float):
        self.c = c
        """The c attribute"""

[machow]

Let's track in this issue, which discusses more on rendering the attributes section, vs attributes individually:

• feat: type annotations for @properties #284