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!"""
    arc.print(f"Hello {name}!")


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

DESCRIPTION
    My first arc program!

ARGUMENTS
    name

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

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

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)  Displays this help message

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
import arc

cli = arc.namespace("cli")


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


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

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


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

DESCRIPTION
    Documentation using descriptions

ARGUMENTS
    firstname    Someone's first name

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

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

DESCRIPTION
    Documentation in docstring

ARGUMENTS
    firstname    Someone's first name

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

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.