command-line-documentation


Generates Markdown "user guide" based off CLI spec compatible with [command-line-args]() and [command-line-usage]().

___ALPHA status software___: The main documentaiton feature is working but we expect to add significant new functionality and improve ease of use before GA.

- Install
- Usage
- Library usage
- cld usage
- Example output
- User reference
- Library API
- CLI spec data structure
- CLI reference

Install

``bash
npm i command-line-documentation
`

Usage

$3

To create self-documenting CLIs.

`javascript
// for ESM
import { commandLineDocumentation/, convertCLISpecTypes / } from 'command-line-documentation'
import commandLineArgs from 'command-line-args'
// for CJS
// const { commandLineDocumentation } = require('command-line-documentation')
// const commandLineArgs = require('command-line-args')

const mainCommand = 'do-it'
const cliSpec = {
mainCommand,
arguments: [
{ name: 'verbose', alias: 'v', type: Boolean, description: 'Makes the output chatty.'},
{ name: 'document', type: Boolean, description: Generates Markdown documentation for '${mainCommand}'.}
]
}

const options = commandLineArgs(cliSpec.arguments)

if (options.document === true) {
commandLineDocumentation(cliSpec)
process.exit(0)
}
`

$3

To generate documentation from a YAML or JSON spec file:

`bash
npx cld path/to/cli-spec.yaml
`

To append CLI documentation to README.md:

`bash
npx cld src/cli-spec.mjs --section-depth 2 --titles 'Command line reference'
`

Example output

You can see this package's cld documentation here.

Processing the example CLI spec would generate:
`markdown


widget-maker Command Reference

Usage

widget-maker [command]

Main options

|Option|Description|
|------|------|
|[command]|(_main argument_, _req_) The command to execute.|
|--verbose, -v|(_bool_, _opt_) Makes the output a bit more chatty.|

Commands

- create: Creates a new widget.
- help: With no command specified, prints a list of available commands or, when a command is specified, prints help for the specified command.





$3

widget-maker create [type]

Creates a new widget.

#### create options

|Option|Description|
|------|------|
|[type]|(_main argument_, _req_) The type of the widget to create.|

#### Subcommands

- chart: Creates a chart widget
- summary: Creates a summary widget.


##### chart

widget-maker create chart

Creates a chart widget

###### chart options

|Option|Description|
|------|------|
|--chart-type|(_string_, _req_) The type of chart to create. May be 'bar' or 'line'.|


##### summary

widget-maker create summary

Creates a summary widget.




$3

widget-maker help

With no command specified, prints a list of available commands or, when a command is specified, prints help for the specified command.


#### help options

|Option|Description|
|------|------|
||(_main argument_, _opt_) The command to print help for.|
`

User reference

$3

#### commandLineDocumentation(, [options])

Generates Markdown documentation based on the CLI spec data structure. The documentation is in a self-contained "section" whose initial header determined by the depth option.

__Arguments__:
- cliSpec: (_object_) a CLI spec data structure.
- options.mainCommand: (_string_) the name of the command being documented. This will override the mainCommand field in the CLI spec (if defined).
- options.sectionDepth: (_integer_, default: 1) a depth of '1' (the default) makes the initial section a title ('#') heading. A depth of two would generate an H1/## heading, etc.
- options.title: (_string_, default: _dynamic_) specifies the primary section heading (title). If not specified, will default to "\${mainCommand}\ Command Reference".

#### convertCLISpecTypes()

Converts a file-based CLI spec (which is pure YAML/JSON) to a CLI spec data structure by converting string types like 'Boolean' to the actual function Boolean. Accepts types 'Boolean', 'Number', and 'String'. Any other 'type' value will raise an exception.

__Arguments__:
- cliSpec: (_object_) a CLI spec data structure except that the 'types' are represented by strings rather than functions.

$3

The following is a comprehensive CLI spec example. It results in the example output above.

`yaml
mainCommand: widget-maker
arguments:
- name: command
description: The command to execute.
defaultOption: true
required: true
type: String
- name: verbose
description: Makes the output a bit more chatty.
alias: v
type: Boolean
commands:
- name: create
summary: Creates a new widget.
arguments:
- name : type
defaultOption : true
description : The type of the widget to create.
required: true
# type defaults to String
commands:
- name: chart
description: Creates a chart widget
arguments:
- name: chart-type
description: The type of chart to create. May be 'bar' or 'line'.
required: true
- name: summary
description: Creates a summary widget.
- name: help
summary: >
With no command specified, prints a list of available commands or, when a command
is specified, prints help for the specified command.
arguments:
- name: command
defaultOption: true
description: The command to print help for.
`

$3

#### Usage

cld [cli-spec-path]

#### Options

|Option|Description|
|------|------|
|[cli-spec-path]|(_main argument_, _req_) The path to the YAML/JSON CLI spec file or Javascript file exporting cliSpec.|
|--section-depth|(_integer_, _opt_, default: 1) A depth of 1 (the default) makes the initial section a title (H1/'#') heading. A depth of 2 would generate an H2/'##' heading, etc.|
|--title|(_string_, _opt_, default: see description) Specifies the primary section heading (title). By default, this is the mainCommand` + " Command Reference".|