JP-3471 improve Step.spec attribute formating in docs (#8101)

CHANGES.rst

@@ -18,6 +18,8 @@ documentation
 
 - Remove the CRDS PUB notices througout the documentation [#8075]
 
+- Improve Step.spec formatting [#8101]
+
 extract_1d
 ----------
 

docs/conf.py

@@ -21,12 +21,40 @@
 import sphinx
 import stsci_rtd_theme
 
+from stpipe import Step
+from sphinx.ext.autodoc import AttributeDocumenter
+
+
+class StepSpecDocumenter(AttributeDocumenter):
+    def should_suppress_value_header(self):
+        if self.name == "spec" and issubclass(self.parent, Step):
+            # if this attribute is named "spec" and belongs to a "Step"
+            # don't show the value, it will be formatted in add_context below
+            return True
+        return super().should_suppress_value_header()
+
+    def add_content(self, more_content):
+        super().add_content(more_content)
+        if self.name != "spec" or not issubclass(self.parent, Step):
+            return
+        if not self.object.strip():
+            return
+
+        # format the long "Step.spec" string to improve readability
+        source_name = self.get_sourcename()
+        self.add_line("::", source_name, 0)
+        self.add_line("  ", source_name, 1)
+        txt = "\n".join((l.strip() for l in self.object.strip().splitlines()))
+        self.add_line(f"  {txt}", source_name, 2)
+
 
 def setup(app):
     try:
         app.add_css_file("stsci.css")
     except AttributeError:
         app.add_stylesheet("stsci.css")
+    # add a custom AttributeDocumenter subclass to handle Step.spec formatting
+    app.add_autodocumenter(StepSpecDocumenter, True)
 
 
 conf = ConfigParser()

docs/jwst/mrs_imatch/index.rst

@@ -10,6 +10,12 @@ MIRI MRS Sky Matching
    :maxdepth: 2
 
    description.rst
+
+**Also See:**
+
+.. toctree::
+   :maxdepth: 1
+
    mrs_imatch_step.rst
 
 .. automodapi:: jwst.mrs_imatch

docs/jwst/mrs_imatch/mrs_imatch_step.rst

@@ -6,6 +6,5 @@ LSQ Equation Construction and Solving
 
 .. currentmodule:: jwst.mrs_imatch.mrs_imatch_step
 
-.. automodule:: jwst.mrs_imatch.mrs_imatch_step
-   :members:
-   :undoc-members:
+.. automodapi:: jwst.mrs_imatch.mrs_imatch_step
+   :noindex:

docs/jwst/skymatch/index.rst

@@ -13,6 +13,11 @@ SkyMatch
    arguments.rst
    reference_files.rst
 
+**Also See:**
+
+.. toctree::
+   :maxdepth: 1
+
    skymatch_step
    skymatch
    skyimage

docs/jwst/skymatch/region.rst

@@ -9,6 +9,5 @@ used by ``skymatch`` to create data masks.
 
 .. currentmodule:: jwst.skymatch.region
 
-.. automodule:: jwst.skymatch.region
-   :members:
-   :undoc-members:
+.. automodapi:: jwst.skymatch.region
+   :noindex:

docs/jwst/skymatch/skyimage.rst

@@ -6,6 +6,5 @@ skyimage
 
 .. currentmodule:: jwst.skymatch.skyimage
 
-.. automodule:: jwst.skymatch.skyimage
-   :members:
-   :undoc-members:
+.. automodapi:: jwst.skymatch.skyimage
+   :noindex:

docs/jwst/skymatch/skymatch.rst

@@ -9,6 +9,5 @@ matching operations on the input image data models.
 
 .. currentmodule:: jwst.skymatch.skymatch
 
-.. automodule:: jwst.skymatch.skymatch
-   :members:
-   :undoc-members:
+.. automodapi:: jwst.skymatch.skymatch
+   :noindex:

docs/jwst/skymatch/skymatch_step.rst

@@ -10,6 +10,5 @@ from the JWST calibration pipeline.
 
 .. currentmodule:: jwst.skymatch.skymatch_step
 
-.. automodule:: jwst.skymatch.skymatch_step
-   :members:
-   :undoc-members:
+.. automodapi:: jwst.skymatch.skymatch_step
+   :noindex:

docs/jwst/skymatch/skystatistics.rst

@@ -9,6 +9,5 @@ functions used by ``skymatch.``
 
 .. currentmodule:: jwst.skymatch.skystatistics
 
-.. automodule:: jwst.skymatch.skystatistics
-   :members:
-   :undoc-members:
+.. automodapi:: jwst.skymatch.skystatistics
+   :noindex:

docs/jwst/tweakreg/astrometric_utils.rst

@@ -8,6 +8,5 @@ set of images.
 
 .. currentmodule:: jwst.tweakreg.astrometric_utils
 
-.. automodule:: jwst.tweakreg.astrometric_utils
-   :members:
-   :undoc-members:
+.. automodapi:: jwst.tweakreg.astrometric_utils
+   :include-all-objects:

docs/jwst/tweakreg/index.rst

@@ -14,7 +14,7 @@ TweakReg
 **Also See:**
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
 
    tweakreg_catalog
    tweakreg_step

docs/jwst/tweakreg/tweakreg_catalog.rst

@@ -7,6 +7,5 @@ of sources from images.
 
 .. currentmodule:: jwst.tweakreg.tweakreg_catalog
 
-.. automodule:: jwst.tweakreg.tweakreg_catalog
-   :members:
-   :undoc-members:
+.. automodapi:: jwst.tweakreg.tweakreg_catalog
+   :noindex:

docs/jwst/tweakreg/tweakreg_step.rst

@@ -8,6 +8,5 @@ from the JWST calibration pipeline.
 
 .. currentmodule:: jwst.tweakreg.tweakreg_step
 
-.. automodule:: jwst.tweakreg.tweakreg_step
-   :members:
-   :undoc-members:
+.. automodapi:: jwst.tweakreg.tweakreg_step
+   :noindex:

docs/jwst/tweakreg/utils.rst

@@ -7,6 +7,5 @@ manually applying corrections to an imaging WCS.
 
 .. currentmodule:: jwst.tweakreg.utils
 
-.. automodule:: jwst.tweakreg.utils
-   :members:
-   :undoc-members:
+.. automodapi:: jwst.tweakreg.utils
+   :noindex:

jwst/tweakreg/astrometric_utils.py

@@ -27,6 +27,9 @@
 """
 
 
+__all__ = ["TIMEOUT", "compute_radius", "create_astrometric_catalog", "get_catalog"]
+
+
 def create_astrometric_catalog(input_models, catalog="GAIADR3", output="ref_cat.ecsv",
                                gaia_only=False, table_format="ascii.ecsv",
                                existing_wcs=None, num_sources=None, epoch=None):