Add docstrings to app title an sub-titles#1570
Conversation
According to the current working of out documentation generation pipeline, this is the way to document a reactive property that is referred to within the owner class' __init__. See Textualize#1572 and Textualize#1564.
|
Is this the pattern for documenting attributes and classvars then? I know you were researching such documentation. What was the conclusion of that? |
See this comment and the one that follows it. That was what I discovered in trying to figure out what was going on here. It's also worth noting that the docs will characterise the property as class or instance depending on where it encounters it last too. I've not seen anything formal in the the documentation for the tools yet (and I'd still like to narrow it down to exactly which tool is responsible for this; for example it looks like this is at the very heart of it), but the approach used in this PR and mentioned in the other comment seems to be the best way of ensuring property docstrings actually make it into out docs, for now anyway. |
As of now this doesn't result in documentation appearing for everything; it seems that something in our documentation chain (perhaps
mkdocstrings) treats properties as case-insensitive; so when there's a docstring forTITLEandtitleonly the former seems to show up in the docs.At some point soon I'll try and isolate this issue to the correct part of the documentation pipeline and make an issue. Meanwhile, this gets docstrings in place (which is also a benefit to development environments which show docstrings).
Edit to add: Testing the mkdocs/mkdocs-material/mkdocstrings pipeline in isolation, this isn't a problem. Need to look into that aspect some more (as an aside from this).