documentation issues

[hydrargyrum]

I think some things are missing in the documentation, but maybe I just couldn't find them (I tried to look in various places and also tried with the search, but didn't find them)

• textual.keys.Keys enum is not present in documentation, so we don't know what keys can be bound easily.
• Similarly, I couldn't find what is the syntax of the Binding(key=xxx) string (is it case sensitive? does it allow control or ctrl? etc)
• for classes, the module to import them from is not indicated, for example, on https://textual.textualize.io/api/binding/ textual.binding.Binding is not mentioned anywhere

[merriam]

You might get faster answers in the discord.

Keys are listed in keys.py, which is both all the listed keys and their textual representation.

I'm unclear on the third part of your question. Are you asking about how the BINDINGS variable is processed?

[merriam]

Sorry, my comment looks terse in retrospect. No emoji anywhere~ 😸

You are suggesting a line n the Guide/Input Bindings section could point to keys.py? Also, removing the paragraph mentioning the Binding Class as the class does not provide more options?

[hydrargyrum]

Keys are listed in keys.py, which is both all the listed keys and their textual representation.

Of course, but I think a library's documentation's role is to avoid having to read the library's source code!

You are suggesting a line n the Guide/Input Bindings section could point to keys.py?

Not merely point to keys.py, include all the enum keys in the documentation, see for example https://doc.qt.io/qt-6/qt.html#Key-enum

for classes, the module to import them from is not indicated, for example, on https://textual.textualize.io/api/binding/ textual.binding.Binding is not mentioned anywhere

The problem is similar, of course I could grep Binding in textual's source code, and see in what file it's present, then import from that file. But I think the documentation could also simply mention that information so the documentation is enough in itself.

There are some projects where there's very little documentation, and by reading it, it's obvious you'll very soon have to read not only the docs but also the source code. By contrast, textual's docs cover many topics, from different point of views (e.g. tutorial, guide, reference, API), it's pretty good, but then its quality makes expect that I don't have to read the source code! ;)

I'm unclear on the third part of your question. Are you asking about how the BINDINGS variable is processed?

Not exactly, for BINDINGS/Binding(), one can use Keys.Left constant, but it's also possible to use "left" string. This should be explicit, and a bit more exhaustive:

• list all Keys enum entries (since the list is finite)
• describe how the string to pass is built, for example Ctrl+A should be passed as the string "ctrl-a" which is not obvious without documentation telling it

[darrenburns]

I agree that modules listed in the reference should include the path of the module.

The title of the API reference for textual.binding is Binding, which confusingly is also the name of a class inside textual.binding.

I think the title of API reference pages for modules should just be the module path, so textual.binding - anything else is pretty confusing.

[willmcgugan]

• textual.keys.Keys enum is not present in documentation, so we don't know what keys can be bound easily.

You really don't need to look at that. It could even be private.

Not all the keys are enumerated, some are derived from their unicode name. You can run the following command to see what is generated when you press a key.

textual keys

• Similarly, I couldn't find what is the syntax of the Binding(key=xxx) string (is it case sensitive? does it allow control or ctrl? etc)

A note somewhere would be useful, sure, but you can see the values of key from the above command.

• for classes, the module to import them from is not indicated, for example, on https://textual.textualize.io/api/binding/ textual.binding.Binding is not mentioned anywhere

That could be improved. You are the first to point it out, probably because most people come from the docs where there is an example of an import.

[willmcgugan]

The docs do display the import path under "Table of Contents", although its not very prominent.

[github-actions]

Don't forget to star the repository!

Follow @textualizeio for Textual updates.