integrate talondoc into knausj?

[rntz]

@wenkokke has a tool called talondoc that allows writing documentation for .talon files using Sphinx, a pretty standard documentation tool. It also extracts 'doc-comments' beginning with a triple hash '###' from .talon files, for example:

my action:
    ### documentation for what "my action" does
    user.foo()

This allows generating a website full of docs; eg. https://wen.works/talondoc/knausj_talon/core/keys/keys.html. With some work on actually writing docs (rather than just autogenerating them) it should be possible to do this in a more tutorial or cheatsheet style, like https://tararoys.github.io/small_cheatsheet. And the tool is also capable of running .py files in a mock-Talon environment to extract information like the values of lists and captures, so eventually it should be possible to use those in documentation as well.

I think it would be really good long-term to:

1. Make a habit out of decorating our .talon files with doc comments.
2. Auto-generate documentation for simple files.
3. Write explicit documentation for very commonly used files / subsystems (eg. text.talon) and captures (the formatter and dictation captures, for instance, are complex but very important).

We discussed the idea of integrating talondoc into knausj_talon in the last knausj grooming session, so that we automatically build docs whenever we push to knausj and push the docs to a website (hosted on GitHub pages). I'm fairly positive about the idea as long as talondoc is reasonably robust and stable. I want to make sure the rest of the maintainers are on-board with this. Concerns, suggestions, ideas?

[rntz]

My main concerns are:

1. We had some stability issues with talonfmt when we integrated it. I think it's clearly been positive overall, but I would like to minimize similar issues here. This should be less of a concern here since we can allow doc-generation to fail without preventing merges/pushes.

2. talondoc has to duplicate a bunch of talon features (parsing .talon files, implementing a mock-registry; it may even do talon command parsing). This is duplicated work, and could slow down knausj dev if talon and talondoc get out of sync.

3. The bus-factor; what if Wen stops developing talondoc? Can someone else step in? What do we do if not?

4. The tradeoff between interactive in-Talon help/documentation versus central, static documentation. I think currently we're kinda bad at both of these, and any improvement in one will likely help with the other down the road.

[pokey]

I am very much in favour of automatically generating documentation for knausj. We're actually moving in a similar direction worth Cursorless

I think that all sounds reasonable, tho prob worth getting feedback from @lunixbochs on format / approach before we invest a bunch of time in adding docs using this format

[wenkokke]

The format for documenting actions was agreed on between @lunixbochs and @pokey at some point: Google style docstrings with interpolation of variables between angular brackets.

(It's probably worth checking if that's still good, though.)

The format for docstrings for .talon files are simply lines starting with ###. Those comments in the bodies of actions are used for its documentation. Those at the start of the .talon file are used as the documentation for the file.

[knausj85]

shouldn't the documentation for this be largely covered by the doc strings for the actions in the python files?

it seems like we're duplicating effort by not using those doc strings; I'm probably missing something

edit: nevermind from: https://wen.works/talondoc/index.html#

TalonDoc will attempt to generate documentation for the command using the following three options, in order:

Use the Talon docstrings in the command script. Talon docstrings are comments which start with ###.

Use the Python docstrings from the actions used in the command script.

Include the command script.

[splondike]

Sounds good to me if lunixbochs approves of the commenting style.