-
-
Notifications
You must be signed in to change notification settings - Fork 9
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
docs: Dynamically pretty-formatting CLI reference
- Loading branch information
1 parent
a4455dd
commit 2e5a7e6
Showing
18 changed files
with
488 additions
and
236 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file was deleted.
Oops, something went wrong.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,65 @@ | ||
| # CLI Reference | ||
|
|
||
| ## Description | ||
|
|
||
| {{ description }}. | ||
|
|
||
| ## Synopsis | ||
|
|
||
| ``` | ||
| {{ synopsis }} | ||
| ``` | ||
|
|
||
| Use `{{ commandName }} {{ helpCommandName }} [command]` for information on a specific command. The following commands are available: | ||
| {% for command in globalCommands %} | ||
| * [{{ command.name }}](#{{ command.name }}) | ||
| {% endfor %} | ||
|
|
||
| ## Options | ||
| {% for option in globalOptions %} | ||
| ### {{ option.pretty }} | ||
|
|
||
| {% if option.required -%} | ||
| `{{- ' REQUIRED' -}}` | ||
| {%- else -%} | ||
| `{{- ' OPTIONAL' -}}` | ||
| {%- endif -%} | ||
| {{- ' | ' -}} | ||
| `{{- option.type }}` | ||
|
|
||
| {{ option.description }} | ||
|
|
||
| {% if option.long %} | ||
| * *Long Option*: `{{ option.long }}` | ||
| {%- endif -%} | ||
| {% if option.short %} | ||
| * *Short Option*: `{{ option.short }}` | ||
| {%- endif -%} | ||
| {% if option.environment %} | ||
| * *Environment Variable*: `{{ option.environment }}` | ||
| {%- endif -%} | ||
| {% if option.defaultValue %} | ||
| * *Default*: `{{ option.defaultValue }}` | ||
| {%- endif -%} | ||
| {% endfor %} | ||
|
|
||
| ## Commands | ||
|
|
||
| {% for command in globalCommands %} | ||
| ### {{ command.name }} | ||
|
|
||
| {{ command.description}} | ||
|
|
||
| Usage: | ||
| ``` | ||
| {{ command.usage}} | ||
| ``` | ||
|
|
||
| {% if command.arguments.length > 0 %} | ||
| Arguments: | ||
| {% for argument in command.arguments %} | ||
| * `{{ argument.name}}` ({% if argument.required -%} `REQUIRED` {%- else -%} `OPTIONAL` {%- endif %}): {{ argument.description }} | ||
| {%- endfor %} | ||
| {% endif %} | ||
|
|
||
| {% endfor %} |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,101 @@ | ||
| // This script generates the CLI reference documentation from the CLI options - if doc root path is provided, it will write the output to the provided path, otherwise it will print to stdout | ||
|
|
||
| import {Argument, Help} from 'commander'; | ||
| import {argParser} from '../src/app/factory.js'; | ||
| import {Liquid} from 'liquidjs'; | ||
| import fs from 'fs/promises'; | ||
| import path from 'path'; | ||
|
|
||
| const outputPath = process.argv.pop() + `/user-guides/cli.md`; | ||
|
|
||
| /** | ||
| * The program from the app factory | ||
| */ | ||
| const program = argParser(() => {}); | ||
| /** | ||
| * Commander js helper to format | ||
| */ | ||
| const helper = new Help(); | ||
|
|
||
| type GlobalCommand = { | ||
| name: string, | ||
| usage: string, | ||
| description: string, | ||
| arguments?: { | ||
| name: string, | ||
| description: string, | ||
| required: boolean | ||
| }[] | ||
| } | ||
|
|
||
| type GlobalOption = { | ||
| pretty: string, | ||
| required: boolean, | ||
| type: string, | ||
| description: string, | ||
| long?: string, | ||
| short?: string, | ||
| environment?: string, | ||
| defaultValue?: string, | ||
| } | ||
|
|
||
| const templateInput = { | ||
| description: program.description(), | ||
| commandName: program.name(), | ||
| helpCommandName: (program as any)._helpCommandName, | ||
| synopsis: helper.commandUsage(program), | ||
| globalCommands: [] as GlobalCommand[], | ||
| globalOptions: [] as GlobalOption[], | ||
| }; | ||
|
|
||
| for (const option of program.options) { | ||
| templateInput.globalOptions.push( | ||
| { | ||
| pretty: option.long!.slice(2), | ||
| long: option.long!, | ||
| short: option.short!, | ||
| environment: (option as any).envVar, | ||
| required: option.mandatory, | ||
| defaultValue: option.defaultValueDescription ?? option.defaultValue?.toString(), | ||
| type: (option.flags.match(/<(.*)>/) ?? [``, `boolean`])[1], | ||
| description: option.description, | ||
| }, | ||
| ); | ||
| } | ||
|
|
||
| for (const command of program.commands) { | ||
| templateInput.globalCommands.push( | ||
| { | ||
| name: command.name(), | ||
| usage: templateInput.commandName + ` [options] ` + command.name() + ((command as any)._args.length > 0 ? ` [arguments]` : ``), | ||
| description: command.description(), | ||
| arguments: [], | ||
| }, | ||
| ); | ||
|
|
||
| for (const argument of (command as any)._args as Argument[]) { | ||
| templateInput.globalCommands[templateInput.globalCommands.length - 1].arguments!.push( | ||
| { | ||
| name: argument.name(), | ||
| description: argument.description, | ||
| required: argument.required, | ||
| }, | ||
| ); | ||
| } | ||
| } | ||
|
|
||
| templateInput.globalOptions.sort((a, b) => a.pretty.localeCompare(b.pretty)); | ||
| templateInput.globalCommands.sort((a, b) => a.name.localeCompare(b.name)); | ||
|
|
||
| const engine = new Liquid(); | ||
| const template = await engine.parseFile(`./build/cli-reference.liquid`); | ||
| const output = await engine.render(template, templateInput); | ||
|
|
||
| try { | ||
| await fs.stat(path.dirname(outputPath)); | ||
| await fs.writeFile(outputPath, output, {encoding: `utf-8`}); | ||
| } catch (err) { | ||
| console.error(`Unable to write to file: ${err.message}`); | ||
| console.log(); | ||
| console.log(output); | ||
| } |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.