Markdown Help Generators

The Markdown help generator is provided by the airline-help-markdown library. It generates help output in Markdown format which is a simple text markup format that can be rendered into HTML.

Available Implementations

The following implementations are available:

• MarkdownGlobalUsageGenerator - Generates help for the entire CLI as a single markdown document
• MarkdownMultiPageGlobalUsageGenerator - Generates help for the entire CLI as a series of separate markdown documents
• MarkdownCommandUsageGenerator - Generates markdown documents for individual commands

Example Usage

Global Help

Using MarkdownGlobalUsageGenerator:

   Cli<ExampleRunnable> cli = new Cli<ExampleRunnable>(ShipItCli.class);
        
   GlobalUsageGenerator<ExampleRunnable> helpGenerator = new MarkdownGlobalUsageGenerator<>();
   try {
       helpGenerator.usage(cli.getMetadata(), System.out);
   } catch (IOException e) {
       e.printStackTrace();
   }

Using MarkdownMultiPageGlobalUsageGenerator:

   Cli<ExampleRunnable> cli = new Cli<ExampleRunnable>(ShipItCli.class);
        
   GlobalUsageGenerator<ExampleRunnable> helpGenerator = new MarkdownMultiPageGlobalUsageGenerator<>();
   try {
       helpGenerator.usage(cli.getMetadata(), System.out);
   } catch (IOException e) {
       e.printStackTrace();
   }

Command Help

Using MarkdownCommandUsageGenerator:

SingleCommand<Price> command = new SingleCommand<Price>(Price.class);

CommandUsageGenerator generator = new MarkdownCommandUsageGenerator();
try {
    generator.usage(null, null, "price", command.getCommandMetadata(), command.getParserConfiguration(), System.out);
} catch (IOException e) {
    e.printStackTrace();
}

Customisation

The main point of customisation for markdown based help is the number of columns to output i.e. the max number of character per line. This defaults to 79 which results in maximum line lengths of 80 characters barring some exceptions.

If you prefer you can create instances of the help generators with a different number of columns e.g.

CommandUsageGenerator = new MarkdownCommandUsageGenerator(120);

Improving this Documentation

This documentation is itself open source and lives in GitHub under the docs/ directory.

I am not a professional technical writer and as the developer of this software I can often make assumptions of knowledge that you as a user reading this may not have. Improvements to the documentation are always welcome, if you have suggestions for the documentation please submit pull requests to the main branch.