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.

See also

If the script isn’t implemented in Python with argparse, refer to the more generic Command-line script topic type instead.

If the script is actually a command-line task, document it with a task topic type instead.

Starter template

Create a new argparse-based script topic from Slack.[1] Open a direct message with @sqrbot-jr and type:

create file

Then select Science Pipelines documentation > Script topic (argparse).

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

.. autoprogram:: lsst.example.bin.examplescript:build_argparser()

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, the topic’s file should be named

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/

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/ might be structured like this:

    #! /usr/bin/env python
    from lsst.example.scripts.exampleScript import main
    if __name__ == "__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(
           epilog='More information is available at')
           help='Message to echo.'
        return parser
    def main():
        args = build_argparser().parse_args()

    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()

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.