Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add docstrings to app title an sub-titles #1570

Merged
merged 5 commits into from
Jan 16, 2023
Merged

Conversation

davep
Copy link
Contributor

@davep davep commented Jan 16, 2023

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 for TITLE and title only 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).

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.
@willmcgugan
Copy link
Collaborator

Is this the pattern for documenting attributes and classvars then?

I know you were researching such documentation. What was the conclusion of that?

@davep davep merged commit 632e828 into Textualize:main Jan 16, 2023
@davep davep deleted the title-docs branch January 16, 2023 15:45
@davep
Copy link
Contributor Author

davep commented Jan 17, 2023

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation Improvements or additions to documentation enhancement New feature or request Task
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Review documentation for app title and sub_title
3 participants