Merge pull request #138 from Roman-Supernova-PIT/u/rknop/docs

Update code so API docs work better

Author: rknop

changes/138.docs.rst

@@ -0,0 +1 @@
+Make API docs look better, add more dependencies to pyproject.toml

docs/api.rst

@@ -7,23 +7,19 @@ phrosty API
 phrosty.imagesubtraction
 ------------------------
 
-.. automodule:: phrosty.imagesubtraction
-   :members:
+.. automodapi:: phrosty.imagesubtraction
 
 phrosty.photometry
 ------------------
 
-.. automodule:: phrosty.photometry
-   :members:
+.. automodapi:: phrosty.photometry
 
 phrosty.pipeline
 ----------------
 
-.. automodule:: phrosty.pipeline
-   :members:
+.. automodapi:: phrosty.pipeline
 
 phrosty.utils
 -------------
 
-.. automodule:: phrosty.utils
-   :members:
+.. automodapi:: phrosty.utils

docs/conf.py

@@ -22,8 +22,19 @@
 # Make sure the phrosty module can be found so we can document the API
 
 sys.path.insert( 0, str( pathlib.Path( '..' ).resolve() ) )
-autodoc_mock_imports = [ 'astropy', 'cupy', 'galsim', 'matplotlib', 'numpy', 'nvtx', 'pandas', 'photutils',
-                         'sfft', 'snpit_utils', 'snappl' ]
+# Ideally, we just need this next variable.  However,
+#  while it works with the autmodule directive,
+#  it does not work with the automodapi directive.
+#  See https://github.com/astropy/sphinx-automodapi/issues/148
+# autodoc_mock_imports = [ 'roman_imsim' ]
+#
+# So, instead, we do it manually.  You will need to add mock to
+# the docs list in [project.optional-dependencies] in pyproject.tom.
+import mock
+things_to_mock = [ 'roman_imsim', 'roman_imsim.utils' ]
+for mod in things_to_mock:
+    sys.modules[ mod ] = mock.MagicMock()
+
 
 
 # -- Project information -----------------------------------------------------

phrosty/imagesubtraction.py

@@ -1,3 +1,5 @@
+__all__ = [ 'gz_and_ext', 'sky_subtract', 'stampmaker' ]
+
 # IMPORTS Standard:
 import os
 import io

phrosty/photometry.py

@@ -1,3 +1,5 @@
+__all__ = [ 'ap_phot', 'psfmodel', 'psf_phot' ]
+
 # IMPORTS Standard:
 import numpy as np
 

phrosty/pipeline.py

@@ -1,3 +1,5 @@
+__all__ = [ 'PipelineImage', 'Pipeline' ]
+
 # Imports STANDARD
 import sys
 import argparse

phrosty/utils.py

@@ -1,3 +1,9 @@
+__all__ = [ 'get_roman_bands', 'read_truth_txt', 'radec_isin', 'get_corners',
+            'get_transient_radec', 'get_transient_mjd', 'get_transient_zcmb',
+            'get_transient_peakmjd', 'get_transient_info', 'transient_in_or_out',
+            'get_mjd_limits', 'get_radec_limits', 'get_mjd', 'pointings_near_mjd',
+            'get_mjd_info', 'get_exptime', 'make_object_table' ]
+
 # IMPORTS Standard:
 import os
 import os.path as pa

pyproject.toml

@@ -17,6 +17,17 @@ classifiers = [
   "Programming Language :: Python"
 ]
 dependencies = [
+  "astropy",
+  "cupy-cuda12x",
+  "galsim",
+  "matplotlib",
+  "numpy",
+  "nvtx",
+  "pandas",
+  "photutils",
+  "snpit-utils",
+  "roman-snpit-snappl",
+  "sfft-romansnpit",
   "towncrier",
   "setuptools_scm",
   "cruft",
@@ -49,7 +60,8 @@ docs = [
     "matplotlib",
     "sphinx",
     "tomli",
-    "graphviz"
+    "graphviz",
+    "mock"
 ]