anti-matter

Antimatter

Flexible command line documentation generation

Why should you care?

You are writing a command line tool in node, and it needs help and usage commands. At the moment, the only simple option is to use the built-in doc generation abilities of a popular arg parser like optimist or commander, but if you don't exclusively use flags for your command line tool, or you have more complex and/or nested command sets, this can end up being messy or impossible.

Antimatter attempts to solve this problem as a tool specifically for documenting command line interfaces in as simple and east-to-read a manner as possible, regardless of how the interface works or how complicated it is.

Installation

npm install antimatter

Usage

Antimatter makes no assumptions about how you have set up your command line interface, it just provides functions that make generating the documentation easier. Let's take a look at a high level example before we dive into it.

var antimatter = require('antimatter');

antimatter({
  title: 'roots cli',
  options: { log: true },
  commands: [{
    name: 'watch',
    required: 'folder',
    optional: ['--no-open', '--no-livereload']
    description: 'watches your project for changes and reloads when detected'
  }, {
    name: 'compile',
    optional: 'path',
    description: 'compiles your project once to the provided <path> or the current directory'
  }]
});

At the moment, antimatter only has one root function - it takes an optional title/header for the doc block, an optional object of options, and either an object or array of objects that represent documented commands. By default it will output a colored and formatted string, ready to print to the command line -- if you pass { log: true } into the options as above, it will console.log it for you. Here's a screenshot of what the above would look like in your terminal.

API Docs

The antimatter function takes an object with three potential properties, title (optional), options (optional), and commands.

Title

String, serves as the header on the set of documented commands. Optional.

Options

• log (boolean): console.log the output
• width (integer): constrain all text to this number of columns
• color (string): main color for the docs. default is red, available values here

Commands

Either an object or array of objects that detail the command or commands you are documenting. Each object can have a few keys:

• name (string): name of the command you are documenting
• required (string/array): optional, required params passed to the command
• optional (string/array): optional, optional commands passed to the command
• description (string): description of the command. wrap any param in angle brackets to highlight it.

License & Contributing

• Details on the license can be found here
• Details on running tests and contributing can be found here