Skip to content

Documentation Generation

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

Example

hello.py
import arc


@arc.command()
def hello(name: str):
    """My first arc program!"""
    print(f"Hello {name}!")


hello()
$ python hello.py --help
USAGE
    hello.py [--help] [--] name

DESCRIPTION
    My first arc program!

ARGUMENTS
    name

OPTIONS
    --help (-h)  Shows help documentation

Docstrings as documentation

As seen above, arc uses function docstrings as a source for documentation. Arc understands the following format for docstrings:

def func():
    """[description]

    # <section-name>
    section body

    with paragraphs!

    # <second-section-name>
    ...
    """

For example, given the following:

docstring_example.py
import arc


@arc.command()
def command():
    """Description for the command. It may
    spread over multiple lines.

    Or even multiple paragraphs! Each section only ends
    when a new section header is detected.

    # Section 1
    Sections can have any content you want in them, all that matters
    is that the header matches the expected syntax.

    # Section 2
    arc will preserve paragraphs (two sequential newlines), but may rewrap
    single new lines. You can prevent this by adding \\b before a block of text.
    this tells arc to use the original text-wrapping.

    \b
    Like this!
    Second line
    Third line
    """


command()
arc will format it as follows:
$ python docstring_example.py --help
USAGE
    docstring_example.py [--help]

DESCRIPTION
    Description for the command. It may spread over multiple lines.

    Or even multiple paragraphs! Each section only ends when a new section
    header is detected.

OPTIONS
    --help (-h)  Shows help documentation

SECTION 1
    Sections can have any content you want in them, all that matters is that
    the header matches the expected syntax.

SECTION 2
    arc will preserve paragraphs (two sequential newlines), but may rewrap
    single new lines. You can prevent this by adding \b before a block of
    text. this tells arc to use the original text-wrapping.

    Like this!
    Second line
    Third line

Paramater Documentation

Command parameters may be documented in two ways.

  1. Using the description argument of Argument / Option / Flag / Param. This option takes precedence if both are present.
  2. Adding an # Arguments section to the docstring with the correct formatting.

For example these two commands:

arguments_documentation.py
from arc import CLI, Argument, Option, Flag

cli = CLI()


@cli.command()
def command1(
    firstname: str = Argument(description="Someone's first name"),
    lastname: str = Option(default="", description="Someone's last name. Optional"),
    reverse: bool = Flag(description="Print the name out in reverse"),
):
    """Documentation using descriptions"""


@cli.command()
def command2(firstname, *, lastname="", reverse: bool):
    """Documentation in docstring

    # Arguments
    firstname: Someone's first name
    lastname: Someone's last name. Optional
    reverse: Print the name out in reverse
    """


cli()
Will produce near-identical output:
$ python arguments_documentation.py command1 --help
USAGE
    arguments_documentation.py command1 [--help] [--reverse] [--lastname
    <...>] [--] firstname

DESCRIPTION
    Documentation using descriptions

ARGUMENTS
    firstname  Someone's first name

OPTIONS
    --help (-h)  Shows help documentation
    --reverse    Print the name out in reverse
    --lastname   Someone's last name. Optional

$ python arguments_documentation.py command2 --help
USAGE
    arguments_documentation.py command2 [--help] [--reverse] [--lastname
    <...>] [--] firstname

DESCRIPTION
    Documentation in docstring

ARGUMENTS
    firstname  Someone's first name

OPTIONS
    --help (-h)  Shows help documentation
    --reverse    Print the name out in reverse
    --lastname   Someone's last name. Optional

Which to use is really up to personal preference, however I prefer to place documentation in the docstring because I think it cleans up the function definition.