Documentation Generation

Every arc application / command comes with a builtin --help flag.

Example¶

hello.py

import arc


@arc.command
def hello(name: str):
    """Greets someone by name"""
    arc.print(f"Hello {name}!")


hello()

$ python hello.py --help
USAGE
    hello.py [-h] name

DESCRIPTION
    Greets someone by name

ARGUMENTS
    name

OPTIONS
    --help (-h)  Displays this help message

Parameter Documentation¶

Command parameters are documented using the desc argument of Argument / Option / Flag.

The following command:

arguments_documentation.py

import arc


@arc.command
def cli(
    firstname: str = arc.Argument(desc="Someone's first name"),
    lastname: str = arc.Option(default="Johnson", desc="Someone's last name. Optional"),
    reverse: bool = arc.Flag(desc="print the name out in reverse"),
):
    """Parameter documentation"""


cli()

Will produce the following help output:

$ python arguments_documentation.py --help
USAGE
    arguments_documentation.py [-h] [--lastname LASTNAME] [--reverse]
    firstname

DESCRIPTION
    Parameter documentation

ARGUMENTS
    firstname    Someone's first name

OPTIONS
    --help (-h)  Displays this help message
    --lastname   Someone's last name. Optional (default: Johnson)
    --reverse    print the name out in reverse

Formatting¶

arc supports a markdown-like syntax for formatting help output.

Example¶

examples/formatting_help.py

import arc


@arc.command
def command():
    """**Command description**. Any text before the first section heading
        will be considered the command description.

    # Section Heading
    You can add a section heading to your help text by using a
    line that starts with a hash followed by a space. Any sections you
    define will be included in the help text below the auto-generated
    sections.

    Paragraphs are separated by blank lines. `arc` will handle wrapping the
    text for pargraphs automatically.

    # Lists
    You can create lists by using the following syntax:

    - This is a list item
    - This is another list item
    - This is a third list item

    # Unformatted text
    You can add unformatted text by surrounding the
    text with three backticks

    ```
        arc will not perform any formatting of this text.
            This lets you fully control how the text is displayed (Like tabbing it in!)
    ```

    `arc` actually takes advantage of this fact
    to have more more control over how the
    Argument and Options are displayed in the help text.
    """


command()

Markdown Example

Syntax¶

The following syntax is supported:

Syntax	Description
`bold`	Bolds Text
`italic`	Italicizes Text
`~~strikethrough~~`	Strikethrough Text
`__underline__`	Underlines Text
`code`	Inline Code Block. Useful for when you want to indicate how to run another command
`[www.example.com]`	Marks text as a link. Colors it with `config.present.color.accent` and underlines it
`[[fg.RED]]red[[/fg.RED]]`	Colors Text. See Colors for more information
`---`	Inserts a horizontal rule

Colors¶

You are able to color text using the [[fg.COLOR]]text[[/fg.COLOR]] syntax. The following objects are available for use: