Help Documentation

By default, a CLI will have a help command installed. This command, given the name of another command, will display helpful documentation to do with that command.

For example, given a basic example:

from arc import CLI

cli = CLI()


@cli.command("hello")
def hello(name: str):
    """
    # Description
        Command that greets someone

    # Arguments
        --name <str>  The person to greet
    """
    print(f"Hello, {name}!")


cli()

We'll get some basic output

$ python3 example.py help hello
USAGE
  cli hello --name <...>

DESCRIPTION
  Command that greets someone

ARGUMENTS
  --name <str>  The person to greet

help analyzes the call signature of the function to produce a basic usage string. It then parses the docstring of the function to provide specific information about the command. The doc string of a function can contain different sections of content. These are denoted with a newline and then # <TITLE> (as seen above with Description and Arguments). The help command will also display additional information, such as possible aliases to the command, or subcommands.

Because description is the most common section you'd be likely to include on any subcommand, arc doesn't require that you include the header. If the docstring begins without a header, it's assumed to be the description. For example, the above docstring can be simplified to:

def hello(name: str):
    """Command that greets someone

    # Arguments
        name=<str>  The person to greet
    """

Arguments Section Parsing

arc can also parse a simple Arguments section of the docstring to provide better and more flexible documentation. This is disabled by default, can can be enabled with config.parse_argument_help=True. Keep in mind that once enabled, all commands with a Arguments section must conform to it's syntax, or an exception will be raised.

Argument Syntax

'''
# Arguments
<argument-name>: <argument-description>
'''

Example

@cli.command(short_args={"first": "f", "last": "f", "reverse": "r"})
def hello(first: str, last: str, reverse: bool):
    """Command that greets someone

    # Arguments
      first: person's first name
      last: person's last name
      reverse: reverse the person's name
      before printing it
    """

$ python example.py help hello
USAGE
  cli hello --first <...> --last <...> [--reverse]

DESCRIPTION
  Command that greets someone

ARGUMENTS
  --first (-f)       person's first name
  --last (-l)        person's last name
  --reverse (-r)     reverse the person's name
                     before printing it