With the LSST Science Pipelines, we include many useful ad hoc scripts. These scripts are included in the
bin/ directories of packages but aren’t command-line tasks. Examples are
dispatch_verify.py of the
verify package and (potentially)
plotSkyMap.py of the
Today we’re releasing tools and guidelines to help you write documentation for these scripts that appears on our documentation sites like pipelines.lsst.io. This post will quickly introduce you to the new templates.
Argparse-based Python scripts
Most of our ad hoc scripts are written in Python and use argparse to define their command-line interfaces. We’ve included the autoprogram directive to make documenting these scripts a snap.
autoprogram reflects the arguments, options, and help messages you’ve already added to your
argparse.ArgumentParser instance into the documentation.
See the Argparse-based script topic type page in the Developer Guide to get started.
You can see an argparse-based script topic in action for the
As the docs state, you need to arrange your script so that an importable function generates the
argparse.ArgumentParser instance. In general, this means that your script in the package’s
bin.src/ directory will be a stub that imports and runs a function like
main() within your package’s Python modules. This pattern has many benefits, though, including enabling unit testing of your script’s business logic.
General ad hoc scripts
You can also document other types of scripts, such as shell scripts. See the Command-line script topic type page in the Developer Guide to get started.
Use sqrbot-jr to get a head start
sqrbot-jr, makes starting documentation pages easy.
In Slack, open a direct message with
sqrbot-jr, then type
Pick either Script topic (argparse) or Script topic (generic) from the list of templates. Fill in the variables, copy the generated boilerplate, and add the new file to the scripts/ subdirectory of the module documentation directory.
More documentation improvements to look forward to
Script documentation is just the first of several documentation tooling features that we plan to ship this summer and fall. In SQR-032 we’ve outlined several essential features and our plans for delivering them, including: doctest-based documentation testing, Jupyter Notebook-based tutorials, integration of the Sphinx build with the
scons harness, and integration of pipelines.lsst.io uploads with the stack-os-matrix Jenkins job. If you’re at all interested in these features, please look over SQR-032 and let us know what you think in this topic.