Generating a help page

Introduction

The argumentor library makes it possible to automatically generate various help page, based on the commands and options that are defined.

Help pages are built using the Argumentor.get_help method:

program.py

from argumentor import Argumentor

argm = Argumentor()
help_page = argm.get_help()

Default help page

By default, the help page will list all available commands, as well as global options. Below is an example of a program that generates the default help page:

program.py (executable)

#!/usr/bin/env python3

import sys
from argumentor import Argumentor
from argumentor.exc import ParsingError

argm = Argumentor()

# define commands
argm.add_command(
    "foo",
    description="do stuff",
)
argm.add_command(
    "bar",
    description="do other stuff",
)
argm.add_command(
    "help",
    description="print this page",
)

# define options
argm.add_option(
    "--global-opt",
    description="this will be displayed",
)
argm.add_option(
    "--non-global-opt",
    command="foo",
    description="this won't show up",
)

try:
    cmd, opts = argm.parse()
except ParsingError as err:
    print(err)
    sys.exit(1)

if cmd.get("help"):
    print(argm.get_help())

When executed with the correct command, the output will look like:

$ ./program.py help
usage: program.py <command> <options>

commands:
  foo            - do stuff
  bar            - do other stuff
  help           - print this page

global options:
  --global-opt   - this will be displayed

Command-specific help page

It is also possible to generate a help page for every command (and the options that are available with it). This can be achieved using the code below:

program.py (executable)

#!/usr/bin/env python3

import sys
from argumentor import Argumentor, Flags
from argumentor.exc import ParsingError

argm = Argumentor()

# define commands
argm.add_command(
    "foo",
    description="do stuff",
)
argm.add_command(
    "bar",
    description="do other stuff",
)
argm.add_command(
    "help",
    description="print command help page",
)

# define options
argm.add_option(
    "--help",
    description="display help about given command",
    flags=Flags.SPECIAL,
)
argm.add_option(
    "--global-opt",
    description="this will be displayed",
)
argm.add_option(
    "--non-global-opt",
    command="foo",
    description="this won't show up",
)

try:
    cmd, opts = argm.parse()
except ParsingError as err:
    print(err)
    sys.exit(1)

if opts.get("--help"):
    if cmd:
        command_used = list(cmd.keys())[0]
        print(
            argm.get_help(
                single_command=command_used,
                print_options_for_command=command_used,
            )
        )
elif cmd.get("help"):
    print(argm.get_help())

Running the program above will result in:

$ ./program.py foo --help
usage: program.py foo <options>

do stuff

options for foo:
  --non-global-opt   - this won't show up

global options:
  --help             - display help about given command
  --global-opt       - this will be displayed

Help page with all options

Additionally, it is possible to display all options in the generated help page, by setting the parameter print_all_options to True:

program.py

from argumentor import Argumentor

argm = Argumentor()

help_page = argm.get_help(
    print_all_options=True
)
print(help_page)

Hidden commands and options

Hiding commands and options

Commands and options (as well as all their aliases) can be hidden from the help page. Whether a command/option should be displayed on the help page is determined when the command/option is registered, using the hide parameter. Below is an example of how to hide a command from the help page:

program.py (executable)

#!/usr/bin/env python3

from argumentor import Argumentor

argm = Argumentor()
argm.add_command(
    "printme",
    description="this will be shown",
)
argm.add_command(
    "hideme",
    description="this will be hidden",
    hide=True,
)

print(argm.get_help())

Executing the script above will result in:

$ ./program.py
usage: program.py <command>

commands:
  printme   - this will be shown

Displaying hidden commands and options

Although commands and options can be hidden, it is possible to force argumentor to print them on the help page, by setting the show_hidden parameter to True:

program.py (executable)

#!/usr/bin/env python3

from argumentor import Argumentor

argm = Argumentor()
argm.add_command(
    "printme",
    description="this will be shown",
)
argm.add_command(
    "hideme",
    description="this will be hidden",
    hide=True,
)

print(argm.get_help(show_hidden=True))

Executing the script above will show:

$ ./program.py
usage: program.py <command>

commands:
  printme   - this will be shown
  hideme    - this will be hidden