Argparse-based script topic type¶

The argparse-based script topic type helps you create reference documentation for ad hoc Python scripts that are packaged with the LSST Stack and use argparse to create their command-line interfaces. This topic type is a specialization of the Command-line script topic type that lets you work more efficiently by automatically creating documentation content from your script’s argparse.ArgumentParser instance.

Starter template¶

The argparse-based script topic template is available in the lsst/templates repository.

For an example script named exampleScript.py, the rendered template looks like this:

.. autoprogram:: lsst.example.bin.examplescript:build_argparser()
   :prog: exampleScript.py
   :groups:

The next sections describe the key components of argparse-based script topics.

File name and location¶

The file must be named after the command-line executable, including any extension. For example, if the script is named myScript.py, the topic’s file should be named myScript.py.rst.

The file should be located in the scripts/ subdirectory of the module documentation directory within a package.

For example, if the module’s namespace is lsst.example, the full path for the file within the package repository is doc/lsst.example/scripts/myScript.py.rst.

The autoprogram directive¶

Everything in an argparse-based script topic is generated from a single autoprogram directive, which is provided by the sphinxcontrib.autoprogram Sphinx extension. autoprogram generates all the content that is described by the script topic type, including the program and option directives for cross-referencing.

To use the autoprogram directive, your script needs to be set up in a particular fashion:

The script needs to be in the bin.src directory of a package, but the script file must defer its implementation to a module inside the package’s Python modules.

For example, a script file bin.src/exampleScript.py might be structured like this:
```
#! /usr/bin/env python

from lsst.example.scripts.exampleScript import main


if __name__ == "__main__":
    main()
```

The argparse.ArgumentParser instance must be generated by an argument-less function. This is critical for letting the autoprogram directive get a copy of the ArgumentParser instance to introspect the command-line interface:

"""Example script that is automatically documented.
"""

from argparse import ArgumentParser


def build_argparser():
    parser = ArgumentParser(
       description=__doc__,
       formatter_class=argparse.RawDescriptionHelpFormatter,
       epilog='More information is available at https://pipelines.lsst.io.')
    )
    parser.add_argument(
       'message'
       help='Message to echo.'
    )
    return parser


def main():
    args = build_argparser().parse_args()
    print(args.message)

In this example, the build_argparser() function generates the ArgumentParser instance.

The argument to the autoprogram directive points to the function in your script’s implementation that generates the ArgumentParser instance. The argument is formatted as {module}:{function}(), with a colon (:) separating the module from the function name. Given the above example, the autoprogram directive is written as:

.. autoprogram:: lsst.example.scripts.exampleScript:build_argparser()
   :prog: exampleScript.py
   :groups:

Set the :prog: field to the name of the command-line executable. If you already set the prog argument in argparse.ArgumentParser, this field is not necessary.

Also, the :groups: field ensures that documentation is organized around argument groups (see argparse.ArgumentParser.add_argument_group), if they exist.

For more information about the autoprogram directive, refer to the sphinxcontrib.autoprogram documentation.