From c340825f7034943ff885606e1a9b655f99874ad1 Mon Sep 17 00:00:00 2001 From: Brett Date: Wed, 29 Nov 2023 12:04:04 -0500 Subject: [PATCH 1/2] improve Step.spec attribute formatting in docs --- CHANGES.rst | 2 ++ docs/conf.py | 28 ++++++++++++++++++++++++++++ 2 files changed, 30 insertions(+) diff --git a/CHANGES.rst b/CHANGES.rst index e6effad2dc..56157e4a10 100644 --- a/CHANGES.rst +++ b/CHANGES.rst @@ -18,6 +18,8 @@ documentation - Remove the CRDS PUB notices througout the documentation [#8075] +- Improve Step.spec formatting [#8101] + extract_1d ---------- diff --git a/docs/conf.py b/docs/conf.py index 067f170652..1f82248140 100644 --- a/docs/conf.py +++ b/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() From 7b5be8a85142d0d83c155b4b6d9f201e31fd4485 Mon Sep 17 00:00:00 2001 From: Brett Date: Wed, 29 Nov 2023 13:59:03 -0500 Subject: [PATCH 2/2] replace automodule with automodapi in docs this allows for improved Step.spec formatting and makes the auto-generated docs more consistent --- docs/jwst/mrs_imatch/index.rst | 6 ++++++ docs/jwst/mrs_imatch/mrs_imatch_step.rst | 5 ++--- docs/jwst/skymatch/index.rst | 5 +++++ docs/jwst/skymatch/region.rst | 5 ++--- docs/jwst/skymatch/skyimage.rst | 5 ++--- docs/jwst/skymatch/skymatch.rst | 5 ++--- docs/jwst/skymatch/skymatch_step.rst | 5 ++--- docs/jwst/skymatch/skystatistics.rst | 5 ++--- docs/jwst/tweakreg/astrometric_utils.rst | 5 ++--- docs/jwst/tweakreg/index.rst | 2 +- docs/jwst/tweakreg/tweakreg_catalog.rst | 5 ++--- docs/jwst/tweakreg/tweakreg_step.rst | 5 ++--- docs/jwst/tweakreg/utils.rst | 5 ++--- jwst/tweakreg/astrometric_utils.py | 3 +++ 14 files changed, 35 insertions(+), 31 deletions(-) diff --git a/docs/jwst/mrs_imatch/index.rst b/docs/jwst/mrs_imatch/index.rst index b5615c5a9c..8f9d2b7a1a 100644 --- a/docs/jwst/mrs_imatch/index.rst +++ b/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 diff --git a/docs/jwst/mrs_imatch/mrs_imatch_step.rst b/docs/jwst/mrs_imatch/mrs_imatch_step.rst index d9d7cb30df..f05235ed39 100644 --- a/docs/jwst/mrs_imatch/mrs_imatch_step.rst +++ b/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: diff --git a/docs/jwst/skymatch/index.rst b/docs/jwst/skymatch/index.rst index b61623a480..a36db35adc 100644 --- a/docs/jwst/skymatch/index.rst +++ b/docs/jwst/skymatch/index.rst @@ -13,6 +13,11 @@ SkyMatch arguments.rst reference_files.rst +**Also See:** + +.. toctree:: + :maxdepth: 1 + skymatch_step skymatch skyimage diff --git a/docs/jwst/skymatch/region.rst b/docs/jwst/skymatch/region.rst index 5a1f67fc3a..4851ca9f3e 100755 --- a/docs/jwst/skymatch/region.rst +++ b/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: diff --git a/docs/jwst/skymatch/skyimage.rst b/docs/jwst/skymatch/skyimage.rst index fe91c62f7f..e4ea83779e 100755 --- a/docs/jwst/skymatch/skyimage.rst +++ b/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: diff --git a/docs/jwst/skymatch/skymatch.rst b/docs/jwst/skymatch/skymatch.rst index 7f5352ede7..8ddf7f58e9 100644 --- a/docs/jwst/skymatch/skymatch.rst +++ b/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: diff --git a/docs/jwst/skymatch/skymatch_step.rst b/docs/jwst/skymatch/skymatch_step.rst index 327ab17838..68dcaabe69 100644 --- a/docs/jwst/skymatch/skymatch_step.rst +++ b/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: diff --git a/docs/jwst/skymatch/skystatistics.rst b/docs/jwst/skymatch/skystatistics.rst index ce03069b2c..021db37081 100755 --- a/docs/jwst/skymatch/skystatistics.rst +++ b/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: diff --git a/docs/jwst/tweakreg/astrometric_utils.rst b/docs/jwst/tweakreg/astrometric_utils.rst index e2791d7a80..faa6056653 100644 --- a/docs/jwst/tweakreg/astrometric_utils.rst +++ b/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: diff --git a/docs/jwst/tweakreg/index.rst b/docs/jwst/tweakreg/index.rst index 9164ed8800..56ddf9aa59 100644 --- a/docs/jwst/tweakreg/index.rst +++ b/docs/jwst/tweakreg/index.rst @@ -14,7 +14,7 @@ TweakReg **Also See:** .. toctree:: - :maxdepth: 2 + :maxdepth: 1 tweakreg_catalog tweakreg_step diff --git a/docs/jwst/tweakreg/tweakreg_catalog.rst b/docs/jwst/tweakreg/tweakreg_catalog.rst index 4efc713837..1a3daed602 100644 --- a/docs/jwst/tweakreg/tweakreg_catalog.rst +++ b/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: diff --git a/docs/jwst/tweakreg/tweakreg_step.rst b/docs/jwst/tweakreg/tweakreg_step.rst index a99278e7ac..7e862dd0ca 100644 --- a/docs/jwst/tweakreg/tweakreg_step.rst +++ b/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: diff --git a/docs/jwst/tweakreg/utils.rst b/docs/jwst/tweakreg/utils.rst index 3f0241a5d3..93f5e4c144 100644 --- a/docs/jwst/tweakreg/utils.rst +++ b/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: diff --git a/jwst/tweakreg/astrometric_utils.py b/jwst/tweakreg/astrometric_utils.py index 905d88e3ce..0144fdbb78 100644 --- a/jwst/tweakreg/astrometric_utils.py +++ b/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):