Skip to content

Documentation Generation

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

import arc

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

$ python --help
USAGE [-h] name

    Greets someone by name


    --help (-h)  Displays this help message

Parameter Documentation

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

The following command:
import arc

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"""

Will produce the following help output:
$ python --help
USAGE [-h] [--lastname LASTNAME] [--reverse]

    Parameter documentation

    firstname    Someone's first name

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


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


import arc

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

    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.


Markdown Example


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
[] 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


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