argparse-script-topic-type.rst

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 :doc:`script-topic-type` that lets you work more efficiently by automatically creating documentation content from your script's argparse.ArgumentParser instance.

.. seealso::

   If the script isn't implemented in Python with `argparse`, refer to the more generic :doc:`script-topic-type` instead.

   If the script is actually a command-line task, document it with a :doc:`task topic type <task-topic-type>` instead.

Starter template

Create a new argparse-based script topic from Slack.[1] Open a |dmw-squarebot| and type:

create file

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

[1]	The argparse-based script topic template is maintained in the lsst/templates repository.

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

.. remote-code-block:: https://raw.githubusercontent.com/lsst/templates/main/file_templates/argparse_script_topic/exampleScript.py.rst
   :language: rst

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 :file:`scripts/` subdirectory of the :ref:`module documentation directory <docdir-module-doc-directories>` within a package.

For example, if the module’s namespace is lsst.example, the full path for the file within the package repository is :file:`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 :doc:`script topic type <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 defined such that the implementation is in a module inside the package's Python modules, with the script function specified in the package's pyproject.toml (see :ref:`add_callable_cli_command_to_your_package` for more information).

  For example, a script file might be implemented as a main function found in lsst.example.scripts.exampleScript and be defined as a command line program called exampleScript.

• 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 ~argparse.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 ~argparse.ArgumentParser instance.

The argument to the autoprogram directive points to the function in your script's implementation that generates the ~argparse.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.