Official website docs could describe full CLI commands args and options
Opened this issue · 2 comments
Again, thanks a lot for this great building block. I've been trying multiple gltf-transform cli commands, and had to refer to the -h help command a few times to understand what arguments and options can be passed to each command, their default values etc - for optimize, draco, etc.
The help returned is really useful as is. It might help newcomers to add the dumps of these help to the docs CLI website itself, maybe in a page labelled commands options, as a sibling of Quickstart and Configuration.
What would be the best approach to include these CLI usage herlpers within the documentation site?
- Simple hacky solution, copy-paste them and update every once in a while?
- Or a better automated way which could run
npx glTF-Transform optimize -hto get help from each command, parse the helper text from all CLI commands and integrate in a built page like cli-deepdive? That helper would probably also help to take snapshots of CLI helpers rather than copy-pasting by hand. - Or build these strings from source
program.command('optimize', 'Optimize model by all available methods').help()content?
Pretty low priority, but do you have any preference? Probably that the option 2 is the way to go - just discovered a nice docs:cli run option which does it this way, in the glTF-Transform/package.json:
Line 30 in 23e2bc6
"docs:cli": "CLI_HELP=\"$(gltf-transform -h --no-editorial)\" && perl -i -0pe 's/\\Q<!-- begin:cli_help -->\\E.*\\Q<!-- end:cli_help -->\\E/<!-- begin:cli_help -->\n\\`\\`\\`plaintext$ENV{'CLI_HELP'}\\n\\`\\`\\`\n<!-- end:cli_help -->/gmsi' packages/docs/src/lib/pages/cli.md",Edit: so could something like this work? Loop over an array of commands we want to retrieve help for (eg optimize merge resize inspect etc), and put them into a cli-deepdive markdown between two discriminative tags, the same way it's done for cli. Cannot execute on my windows environment, nor git bash or WSL:
"docs:clidump": "CLI_HELP=\"$(for cmd in optimize merge resize inspect do gltf-transform $cmd -h --no-editorial)\" && perl -i -0pe 's/\\Q<!-- begin:cli_help -->\\E.*\\Q<!-- end:cli_help -->\\E/<!-- begin:cli_help -->\n\\`\\`\\`plaintext$ENV{'CLI_HELP'}\\n\\`\\`\\`\n<!-- end:cli_help -->/gmsi' packages/docs/src/lib/pages/cli-deepdive.md",
Hi @jo-chemla, thanks for the suggestion! I'd be open to either (2) or (3). The docs:cli script I wrote is a bit unweildy, and it'd be totally fine to replace that with a new JS/TS script in the ./scripts folder. For now perhaps all the commands could be listed on a new page in the docs, called "Commands", under the CLI navigation heading.