Fix spec rendering.

docs/conf.py

@@ -25,12 +25,41 @@
 else:
     import tomllib
 
+from sphinx.ext.autodoc import AttributeDocumenter
+
+from romancal.stpipe import RomanStep
+
+
+class StepSpecDocumenter(AttributeDocumenter):
+    def should_suppress_value_header(self):
+        if self.name == "spec" and issubclass(self.parent, RomanStep):
+            # 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, RomanStep):
+            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)
 
 
 # If extensions (or modules to document with autodoc) are in another directory,