> Ultimately we would like to formalize this schema and a protocol to extract or expose it from apps. This which would allow Trogon to build TUIs for any CLI app, regardless of how it was built. If you are familiar with Swagger, think Swagger for CLIs.
I am working on it here: https://github.com/jdx/usage
It's mostly just a README right now, and I'm still iterating on it, talking to friends, but I think I'm getting close. It's definitely not yet written for the average developer to consume yet either. My hope is within the next month or two I might have a usable alpha release of it. I have a use-case for it now so I think it’s finally ready to happen.
If you have any thoughts on my design lmk.
It gets way too complicated real quick and a lot of things you _dont_ want to expose in documentation. It’s better to generate docs from a spec than the other way around, I’m pretty sure of this now.
At that point it would make sense for them to also make scaffolding generators, meaning the cli author only has to write one spec and don’t have to repeat the effort for their code so much.
I made a process where args are now in a toml file, with some various data for different operations, like whether its available in the CLI or API library, its arg flags, help text required value type, etc. From that, i can generate argparse args, documentation, code for other things, etc. Right now im generating args, docs, and a js code block from the same structure.
Heres the toml file: https://gitlab.com/accidentallythecable-public/prover-suite/...
And some docs that were generated from that: https://gitlab.com/accidentallythecable-public/prover-suite/...
Maybe it will give you some ideas on yours
Specification: https://gitlab.com/accidentallythecable-public/argstruct-spe...
Python module implementing specification: https://gitlab.com/accidentallythecable-public/python-module...
e.g.,
- Apps must always have a --help/-h argument
- Apps that require subcommands or arguments must display "Usage" or "Help" when no subcommand or argument is specified
- When an invalid subcommand or argument is inputted, apps must display "Usage" or "Help"
- Arguments that require a file/resource as a parameter SHOULD use the --file/-f flag where possible (and other standardizing best practices)
Most of this stuff is already built into clap etc. If nothing else, it could remove some of the initial cognitive load.