insert program output directly into docs

.readthedocs.yaml

@@ -47,3 +47,4 @@ python:
       path: .
       extra_requirements:
         - docs
+        - sdp

docs/conf.py

@@ -102,6 +102,7 @@ def check_sphinx_version(expected_version):
     "sphinx_automodapi.smart_resolver",
     "sphinx_asdf",
     "sphinxcontrib.jquery",
+    "sphinxcontrib.programoutput",
 ]
 
 if on_rtd:

docs/roman/pipeline_static_preview.rst

@@ -30,37 +30,9 @@ Usage
 ``roman_static_preview`` includes two convenience commands, ``preview`` and ``thumbnail``, that set
 default options to the static preview requirements.
 
-.. code-block:: shell
-
-	❯ roman_static_preview preview --help
-	Usage: roman_static_preview preview [OPTIONS] INPUT [OUTPUT] [SHAPE]...
-
-	  create a preview image with a north arrow overlay indicating orientation
-
-	Arguments:
-	  INPUT       path to ASDF file with 2D image data  [required]
-	  [OUTPUT]    path to output image file
-	  [SHAPE]...  desired pixel resolution of output image  [default: 1080, 1080]
-
-	Options:
-	  --compass / --no-compass  whether to draw a north arrow on the image
-	                            [default: compass]
-	  --help                    Show this message and exit.
-
-.. code-block:: shell
-
-	❯ roman_static_preview thumbnail --help
-	Usage: roman_static_preview thumbnail [OPTIONS] INPUT [OUTPUT] [SHAPE]...
-
-	Arguments:
-	  INPUT       path to ASDF file with 2D image data  [required]
-	  [OUTPUT]    path to output image file
-	  [SHAPE]...  desired pixel resolution of output image  [default: 300, 300]
+.. program-output:: roman_static_preview preview --help
 
-	Options:
-	  --compass / --no-compass  whether to draw a north arrow on the image
-	                            [default: no-compass]
-	  --help                    Show this message and exit.
+.. program-output:: roman_static_preview thumbnail --help
 
 Examples
 --------

pyproject.toml

@@ -48,6 +48,7 @@ docs = [
     'sphinx-rtd-theme',
     'stsci-rtd-theme',
     'sphinx-autobuild',
+    'sphinxcontrib-programoutput',
     'tomli; python_version <="3.11"',
 ]
 test = [

romancal/scripts/static_preview.py

@@ -4,6 +4,9 @@
 import asdf
 import numpy
 
+DEFAULT_PREVIEW_SHAPE = (1080, 1080)
+DEFAULT_THUMBNAIL_SHAPE = (300, 300)
+
 
 def command():
     try:
@@ -33,14 +36,15 @@ def preview(
         shape: Annotated[
             Optional[tuple[int, int]],
             typer.Argument(help="desired pixel resolution of output image"),
-        ] = (1080, 1080),
+        ] = DEFAULT_PREVIEW_SHAPE,
         compass: Annotated[
             Optional[bool],
             typer.Option(help="whether to draw a north arrow on the image"),
         ] = True,
     ):
-        """
-        create a preview image with a north arrow overlay indicating orientation
+        f"""
+        create a {DEFAULT_PREVIEW_SHAPE} preview image from an ASDF file
+        containing a Roman ``ImageModel``, with a north arrow overlay indicating orientation
         """
 
         if output is None:
@@ -76,12 +80,17 @@ def thumbnail(
         shape: Annotated[
             Optional[tuple[int, int]],
             typer.Argument(help="desired pixel resolution of output image"),
-        ] = (300, 300),
+        ] = DEFAULT_THUMBNAIL_SHAPE,
         compass: Annotated[
             Optional[bool],
             typer.Option(help="whether to draw a north arrow on the image"),
         ] = False,
     ):
+        f"""
+        create a {DEFAULT_THUMBNAIL_SHAPE} thumbnail image from an ASDF file
+        containing a Roman ``ImageModel``
+        """
+
         if output is None:
             output = Path.cwd()
         if output.is_dir():