Widget documentation sweep #1909
Conversation
Header.show_clock was just a good old plain object attribute, not a reactive, and also wasn't done as a read-only property. This means someone could get the impression that it could be modified on the fly and the header would react. There might be an argument for turning it into that; but for the moment this commit makes it private so that nobody gets the wrong impression.
While it's arguably not the most useful widget, it's in the code, exported, and can be seen by people; I feel it should be in the documentation. I've ensured that it also links to Placeholder given it sort of is a Placeholder and so people might arrive at it first and it makes sense to redirect them to something more comprehensive.
Delivering on a promise made in Textualize#1920.
Delivering on a promise made in Textualize#1920.
Delivering on a promise made in Textualize#1920.
Delivering on a promise made in Textualize#1920.
Delivering on a promise made in Textualize#1920.
Delivering on a promise made in Textualize#1920.
Delivering on a promise made in Textualize#1920.
Delivering on a promise made in Textualize#1920.
Delivering on a promise made in Textualize#1920.
davep
requested review from
willmcgugan,
rodrigogiraoserrao and
darrenburns
and removed request for
willmcgugan and
rodrigogiraoserrao
| force: Force scrolling even when prohibited by overflow styling. Defaults to `False`. | ||
| x: X coordinate (column) to scroll to, or `None` for no change. | ||
| y: Y coordinate (row) to scroll to, or `None` for no change. | ||
| animate: Animate to new scroll position. |
There was a problem hiding this comment.
I think the sentence "Animate to new scroll position" is a bit cryptic.
Do you think something like "Whether to animate the scrolling (or otherwise just jump to the new position)" or something along those lines is an improvement?
Do you have a better alternative?
There was a problem hiding this comment.
Happy to have improvements made to it; I was just cleaning up prior docs really.
| """Initialise the header widget. | ||
|
|
||
| Args: | ||
| show_clock: ``True`` if the clock should be shown on the right of the header. |
There was a problem hiding this comment.
Is there a difference between surrounding True with a pair of backticks versus two pairs of backticks? I have seen both and haven't understood the difference yet.
There was a problem hiding this comment.
Good question; I was asking myself the same thing as I was going through the docstrings and seeing a difference. I tested it and from what I can tell there's zero difference; both have the same effect (my uninformed guess here would be it's mkdocstrings or something supporting a couple of other doc systems' styles).
| @@ -27,7 +30,7 @@ class TextLog(ScrollView, can_focus=True): | |||
| } | |||
| """ | |||
|
|
|||
| max_lines: var[int | None] = var(None) | |||
| max_lines: var[int | None] = var[Optional[int]](None) | |||
There was a problem hiding this comment.
As far as my understanding goes, var is just an "alias" for a quick way to create a reactive attribute with some parameters in pre-defined values.
Would it be worth typing max_lines as max_lines: reactive[int | None] = var[Optional[int]](None)?
(This was not a rhetoric question.)
There was a problem hiding this comment.
What benefit do we get from that? A downside I can see is that it might be confusing to a reader of the code, seeing two "different" types like that.
Co-authored-by: Rodrigo Girão Serrão <[email protected]>
Co-authored-by: Rodrigo Girão Serrão <[email protected]>
Co-authored-by: Rodrigo Girão Serrão <[email protected]>
Co-authored-by: Rodrigo Girão Serrão <[email protected]>
Co-authored-by: Rodrigo Girão Serrão <[email protected]>
Co-authored-by: Rodrigo Girão Serrão <[email protected]>
A wander through various widgets, adding missing docstrings, trying to make others better fit in with our standards, and with the occasional type hint tweak where necessary.
See #1811.
Also delivers on the
scroll_docstring promise made in #1902.NOTE: Part of this PR also experiments with a slight change to the layout of the API docs; currently only with the
Tree. Rather than documentTreeandTreeNodeas two very different things, it documents them both underTree. This means that it's then possible to document some of the other public-facing types without the reader having to try and guess which might relate toTree, which toTreeNode, and which to both (and then guess which will be living where).