Command-line script topic type¶
The script topic type provides a common documentation format for describing ad hoc scripts that are packaged with the LSST Stack. This topic type is oriented towards creating reference documentation; these topics are the canonical descriptions for a script’s command-line arguments, options, and functionality. Other topics, like how-to guides and tutorials, can link to these descriptions.
This script topic type works for any type of command-line executable (like shell scripts and compiled C++ executables) and relies on manually writing the usage, and documentation for options and arguments.
If your script is written in Python and uses
argparse, you can automate this reference documentation by using the argparse-based variant of the script topic type.
If the script is actually a command-line task, document it with a task topic instead.
The script topic file template is available in the lsst/templates repository.
The script topic template sets technical details like names and labels for sections. Starting from the template is the best way to follow the script topic standard.
For an example script named
exampleScript.sh, the rendered template looks like this:
.. program:: exampleScript.sh ################ exampleScript.sh ################ .. Summary sentence that describes what the script does goes here. .. In additional paragraphs, add extra documentation. .. code-block:: text Usage: exampleScript.sh [OPTIONS]... [ARGS] .. Positional arguments .. ==================== .. .. .. option:: fixme .. .. FIXME description of a positional argument. Optional arguments ================== .. option:: -h Print the help message.
The next sections describe the key components of 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
myScript.py, the topic’s file should be named
The file must 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 is
The topic of the script topic file should have a program directive with the executable’s name as an argument:
.. program:: exampleScript.sh
This allows you to associate option directives further down the page with this executable in cross-references.
The title (top-level header) is the executable’s name (what you would type on the command line, assuming the executable is in the
$PATH), without any special formatting (like code literals).
Directly below the title, write a sentence that says what the script is for. Think of this sentence as a subtitle that helps a reader quickly understand what the script is for, without getting into too much detail.
After the summary sentence (a paragraph of its own), you can add additional paragraphs that discuss functionality in depth, and provide small examples of how the script might be used.
If necessary, organize these paragraphs into subsections.
Before the options and arguments are documented, include a usage message inside a code-block directive.
Positional arguments (optional section)¶
The section named “Positional arguments” is where you document command-line arguments that are positional. Leave this section out if there aren’t any positional arguments.
Document each argument with an option directive. For example:
.. option:: file Path of an input file.
Optional arguments (optional section)¶
The section named “Optional arguments” is where you document options, like the
-h option to produce a help message.
Leave this section out if there aren’t any optional arguments.
Document each optional argument using the option directive, including the dash character (
.. option:: -h, --help Print the help message and exit.
Notice how both the short and long forms of an option can be documented together. Of course, options don’t need to have both forms.
The option directive also works with options that have operands:
.. option:: --ref gitref The Git commit SHA, tag, or branch name.
Grouped argument sections (optional sections)¶
If the command-line interface has a large number of options, you might want to organize them into their own sections.
This corresponds to how you would use the
argparse.ArgumentParser.add_argument_group method in Python scripts.
Make sure the section name ends with the word “arguments” and start the section name with the name of the group. The content of this section is also made up of option directives.
Positional arguments ==================== .. option:: file Path to the file Optional arguments ================== .. option:: -h, --help Print the help message and exit. .. option:: --verbose Enable verbose logging. XYZ arguments ============= .. option:: --flag1 bar Description of flag1. .. option:: --flag2 Description of flag2.