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

npm i command-line-documentation

Usage

Library usage

To create self-documenting CLIs.

// 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)
}

cld usage

To generate documentation from a YAML or JSON spec file:

npx cld path/to/cli-spec.yaml

To append CLI documentation to README.md:

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:

# `widget-maker` Command Reference

## Usage

`widget-maker <options> [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`](#widget-maker-create): Creates a new widget.
- [`help`](#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.


<span id="widget-maker-create"></span>
### `create`

`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`](#widget-maker-create-chart): Creates a chart widget
- [`summary`](#widget-maker-create-summary): Creates a summary widget.

<span id="widget-maker-create-chart"></span>
##### `chart`

`widget-maker create chart <options>`

Creates a chart widget

###### `chart` options

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

<span id="widget-maker-create-summary"></span>
##### `summary`

`widget-maker create summary`

Creates a summary widget.

<span id="widget-maker-help"></span>
### `help`

`widget-maker help <command>`

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|
|------|------|
|`<command>`|(_main argument_, _opt_) The command to print help for.|

User reference

Library API

commandLineDocumentation(<cliSpec>, [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(<cliSpec>)

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.

CLI spec data structure

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

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.

CLI reference

Usage

cld <options> [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".|