[Docs] Automate docs generation for BINDINGS et al

[rodrigogiraoserrao]

A widget's BINDINGS and COMPONENT_CLASSES have tables that are partially generated by tools/widget_documentation.py but that must be kept updated by hand.

Investigate whether we can make a mkdocs/mkdocstrings plugin that inspects attributes like BINDINGS and COMPONENT_CLASSES to build their tables on the fly.

What about DEFAULT_CSS? Can we document their values (e.g., by setting the docstring to match the string value itself)?

[willmcgugan]

Default css is not a bad idea. Could be very useful in docs.

[rodrigogiraoserrao]

Default css is not a bad idea. Could be very useful in docs.

Yup. That was more of a rhetoric question so that I wouldn't forget about it. The default css should definitely be documented but the only obvious alternative I know of would make the full string appear inlined with the attribute in the header... Which is not what we want.

With the plugin we could inject it into the docstring and surrounded by backticks to style it as Textual CSS.

[rodrigogiraoserrao]

For widgets, can we collect all the attributes that are reactive and list them in a separate table? E.g., to include them in the reference pages.

[merriam]

OK, so I wrote a hack with tree_sitter and can parse out CSS_DEFAULTS from Python, then parse it as a CSS language.

Now what?

Consider this rule:

     DataTable {
        background: $surface ;
        color: $text;
        height: auto;
        max-height: 100%;
    }

• DataTable is redundant in every other rule, like but maybe not here. In rules like DataTable:dark and DataTable > .datatable--even-row, how should it be displayed?
• All the words can be from a dictionary lookup: background, $surface, color, ..., "100%". That is, they could be hover text or links to documentation-wide glossary. height: auto means the same regardless of the widget, and it has a meaning distinct from leaving height blank. There are some words, like .datatable--even-row that are unique to one widget. So links and hover text in a big config file?
• Comments are allowed or not allowed in .tcss; can I have # Styling for zebra strips\nDataTable > .datatable--even-row {...?
• I could just return a dict for someone else to format the output. That is:

  DataTable > .datatable--even-row {
      background: $primary 10%;
  }

  gives {"DataTable > .datatable--even-row": {"background": ["$primary", "10%"]}

Outside of DEFAULT_CSS, what else should get parsed?

[merriam]

Just as an FYI. I'm still playing with this:

• I use tree sitter to extract the DEFAULT_CSS and then tree sitter to extract out the rule sets and declarations. Nested rule sets are flattened to their final selections.
• I can pull all usages of DEFAULT_CSS into a single 'monster_defaults.py' file and can parse it. So far, no DEFAULT_CSS uses !important, or nests more than three levels. A small, enumerated number of Pseudo-classes are used, but not pseudo-attributes. CSS keeps adding new pseudo-classes, e.g., nth-child(3) which Textual does not support.
• I ended up using textual.document._syntax_aware_document to parse as tree sitter is difficult to configure. I also use some custom tree walking functions instead of the stateful tree sitter cursor and query model.
• I'm trying to pull the COMPONENT_CLASSES table and just add the default values.
• • verify COMPONENT_CLASSES is correct by looking at all strings having '--'.
• • pull the comments from the table right after COMPONENT_CLASSES table, which is hand edited.
• • render this at doc-build time by running the code from mkdocs.
• • render DEFAULT_CSS that is not in COMPONENT_CLASSES as a table, usually with only a couple entries.
• • render a list full of links for all attributes set by default, including from bases.

If anyone wishes, I can post the code so far (tools/widget_walk.py and tools/test_widget_walk*).