Meta, Docs: Reactive attributes that are assigned to inside __init__ need to be documented inside __init__

[davep]

[Note that the subject of this issue has been modified to reflect the conclusion of this issue]

This is a bit of a meta issue that affects how the Textual docs are generated. I'm creating it as a fresh issue in our own repo as it's not obvious to me at the moment what the cause of the problem is, and I also can't recreate it in isolation right now.

This initially stems from #1564, where when I created #1570 to add docstrings for TITLE, title, SUB_TITLE and sub_title, only the upper-cased versions of those class attributes appear in the docs. I created this repo to try and isolation the problem, and see what part of the documentation pipeline might be responsible, but the result there is fine:

So.. hence this issue. I'll track what I find here and if I find that some other tool is responsible (rather than it being a configuration issue for our docs, for example) I'll then go on to raise an issue there.

[davep]

Turns out it's not even something global to the Textual docs. If I add two class-attributes to Header (as a test on a small class), called FOO and foo, they come out just fine:

[davep]

Going back to App to see if there's something special about that and... adding FOO and foo there and they come out fine.

So it looks like there's something special about title and sub_title.

[davep]

I think I've finally narrowed it down. It isn't about different-case at all! It's if there's a reference to an instance attribute within __init__ that matches the class attribute, the class attribute seems to get ignored. Taking mouse_over as another test -- which is only introduced in __init__ -- no documentation appears for it if I introduce it as a class attribute.

[davep]

So, to conclude, if a class has a reactive, that is assigned to inside the class' __init__, the docstring for the reactive should go with the assignment inside __init__ rather than its declaration on the class itself. In other words, not this:

class Foo( Widget ):

    bar = reactive( "" )
    """This is the docstring"""

    def __init__( self, baz: str ) -> None:
        self.bar = baz

But this:

class Foo( Widget ):

    bar = reactive( "" )

    def __init__( self, baz: str ) -> None:
        self.bar = baz
        """This is the docstring"""

Doing the former causes mkdocstrings(?) to see the reactive as not having documentation.

[github-actions]

Don't forget to star the repository!

Follow @textualizeio for Textual updates.

[davep]

Right, nope, it's still not what I discovered above; there's a further refinement to this. It isn't that the content of __init__ wins in the situations mentioned above, it's that whichever mention of the class attribute or instance attribute is seen second wins -- it's the one that needs the docstring. So, further to the two examples given above, this results in working documentation too:

class Foo( Widget ):

    def __init__( self, baz: str ) -> None:
        self.bar = baz

    bar = reactive( "" )
    """This is the docstring"""

[rodrigogiraoserrao]

@davep as of yesterday, griffe got the PR mkdocstrings/griffe#135 that fixes this so that 0.25.6 will preserve the docstring it finds if it is the only one.