Merge 0cbae50 into 2a1d85d

README.rst

@@ -2,10 +2,24 @@
 DESI Survey Planning and Scheduler
 ==================================
 
+|Actions Status| |Coveralls Status| |Documentation Status|
+
+.. |Actions Status| image:: https://github.com/desihub/desisurvey/workflows/CI/badge.svg
+    :target: https://github.com/desihub/desisurvey/actions
+    :alt: GitHub Actions CI Status
+
+.. |Coveralls Status| image:: https://coveralls.io/repos/desihub/desisurvey/badge.svg
+    :target: https://coveralls.io/github/desihub/desisurvey
+    :alt: Test Coverage Status
+
+.. |Documentation Status| image:: https://readthedocs.org/projects/desisurvey/badge/?version=latest
+    :target: https://desisurvey.readthedocs.io/en/latest/
+    :alt: Documentation Status
+
 Introduction
 ------------
 
-This package provides the tools to plan and schedule observations of the 
+This package provides the tools to plan and schedule observations of the
 predefined tiles in the DESI footprint, each associated with an
 observing program (DARK/GRAY/BRIGHT). The algorithms in this package
 do not deal with individual targets or their assignment to fibers.
@@ -21,26 +35,7 @@ Full Documentation
 
 Please visit `desisurvey on Read the Docs`_
 
-.. image:: https://readthedocs.org/projects/desisurvey/badge/?version=latest
-    :target: http://desisurvey.readthedocs.io/en/latest/
-    :alt: Documentation Status
-
-.. _`desisurvey on Read the Docs`: http://desisurvey.readthedocs.io/en/latest/
-
-Travis Build Status
--------------------
-
-.. image:: https://img.shields.io/travis/desihub/desisurvey.svg
-    :target: https://travis-ci.org/desihub/desisurvey
-    :alt: Travis Build Status
-
-
-Test Coverage Status
---------------------
-
-.. image:: https://coveralls.io/repos/desihub/desisurvey/badge.svg?service=github
-    :target: https://coveralls.io/github/desihub/desisurvey
-    :alt: Test Coverage Status
+.. _`desisurvey on Read the Docs`: https://desisurvey.readthedocs.io/en/latest/
 
 License
 -------

doc/Makefile

@@ -2,7 +2,7 @@
 #
 
 # You can set these variables from the command line.
-SPHINXOPTS    =
+SPHINXOPTS    = -W --keep-going
 # For macports, use the second line...
 SPHINXBUILD   = sphinx-build
 #SPHINXBUILD   = sphinx-build-2.7

doc/api.rst

@@ -25,6 +25,24 @@ desisurvey.etc
 .. automodule:: desisurvey.etc
     :members:
 
+desisurvey.forecast
+-------------------
+
+.. automodule:: desisurvey.forecast
+    :members:
+
+desisurvey.holdingpen
+---------------------
+
+.. automodule:: desisurvey.holdingpen
+    :members:
+
+desisurvey.NTS
+--------------
+
+.. automodule:: desisurvey.NTS
+    :members:
+
 desisurvey.optimize
 -------------------
 
@@ -49,22 +67,28 @@ desisurvey.rules
 .. automodule:: desisurvey.rules
     :members:
 
-desisurvey.tiles
-----------------
-
-.. automodule:: desisurvey.tiles
-    :members:
-
 desisurvey.scheduler
 --------------------
 
 .. automodule:: desisurvey.scheduler
     :members:
 
-desisurvey.forecast
--------------------
+desisurvey.svstats
+------------------
 
-.. automodule:: desisurvey.forecast
+.. automodule:: desisurvey.svstats
+    :members:
+
+desisurvey.tileqa
+-----------------
+
+.. automodule:: desisurvey.tileqa
+    :members:
+
+desisurvey.tiles
+----------------
+
+.. automodule:: desisurvey.tiles
     :members:
 
 desisurvey.utils
@@ -76,6 +100,24 @@ desisurvey.utils
 Command-Line Scripts
 ====================
 
+afternoon_plan
+--------------
+
+.. automodule:: desisurvey.scripts.afternoon_plan
+    :members:
+
+collect_etc
+-----------
+
+.. automodule:: desisurvey.scripts.collect_etc
+    :members:
+
+run_plan
+--------
+
+.. automodule:: desisurvey.scripts.run_plan
+    :members:
+
 surveyinit
 ----------
 

doc/changes.rst

@@ -5,8 +5,11 @@ desisurvey change log
 0.19.1 (unreleased)
 -------------------
 
+* Update API documentation for completeness (PR `#151`_).
 * Harden AP against NaNs in offline pipeline EFFTIMEs; zero such cases.
 
+.. _`#151`: https://github.com/desihub/desisurvey/pull/151
+
 0.19.0 (2022-05-13)
 -------------------
 

doc/conf.py

@@ -16,7 +16,7 @@
 
 import sys
 import os
-import os.path
+from importlib import import_module
 
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
@@ -133,58 +133,14 @@
 # This value contains a list of modules to be mocked up. This is useful when
 # some external dependencies are not met at build time and break the
 # building process.
-autodoc_mock_imports = ['astropy',
-                        'astropy.coordinates',
-                        'astropy.io',
-                        'astropy.io.fits',
-                        # 'astropy.modeling',
-                        # 'astropy.stats',
-                        'astropy.table',
-                        'astropy.time',
-                        'astropy.units',
-                        'astropy.utils.data',
-                        'astropy.utils.iers',
-                        'astropy.utils.exceptions',
-                        'astropy.wcs',
-                        'astropy._erfa.core',
-                        'desimodel',
-                        'desimodel.io',
-                        'desimodel.weather',
-                        'desiutil',
-                        'desiutil.log',
-                        'desiutil.plots',
-                        'ephem',
-                        'healpy',
-                        'matplotlib',
-                        'matplotlib.animation',
-                        'matplotlib.colors',
-                        'matplotlib.gridspec',
-                        'matplotlib.pyplot',
-                        # 'matplotlib.patches',
-                        # 'matplotlib.backends',
-                        # 'matplotlib.backends.backend_pdf',
-                        # 'matplotlib.cm',
-                        # 'matplotlib.collections',
-                        'numpy',
-                        'numpy.ma',
-                        # 'numpy.polynomial',
-                        # 'numpy.polynomial.legendre',
-                        'pandas',
-                        'scipy',
-                        # 'scipy.constants',
-                        'scipy.interpolate',
-                        # 'scipy.linalg',
-                        # 'scipy.ndimage',
-                        # 'scipy.optimize',
-                        # 'scipy.sparse',
-                        # 'scipy.sparse.linalg',
-                        'scipy.special',
-                        # 'scipy.stats',
-                        'speclite',
-                        'speclite.filters',
-                        'specsim',
-                        'specsim.atmosphere',
-                        'yaml']
+autodoc_mock_imports = []
+for missing in ('astropy', 'desimodel', 'desitarget', 'desiutil', 'ephem',
+                'healpy', 'matplotlib', 'numpy', 'pandas', 'scipy', 'speclite',
+                'specsim', 'yaml'):
+    try:
+        foo = import_module(missing)
+    except ImportError:
+        autodoc_mock_imports.append(missing)
 
 # -- Options for HTML output ----------------------------------------------
 

py/desisurvey/NTS.py

@@ -1,38 +1,39 @@
 """
-  Next Tile Selector
+Next Tile Selector
 
-  Based on our google sheet (
-  these are the expected inputs
+Based on our google sheet () these are the expected inputs::
 
-        skylevel: current sky level [counts s-1 cm-2 arcsec-2]   (from ETC, at the end of last exposure)
-        seeing: current atmospheric seeing PSF FWHM [arcsec]     (from ETC, at the end of last exposure)
-        transparency: current atmospheric transparency [0-1, where 0=total cloud cover]   (from ETC, at the end of last exposure)
+    skylevel: current sky level [counts s-1 cm-2 arcsec-2]   (from ETC, at the end of last exposure)
+    seeing: current atmospheric seeing PSF FWHM [arcsec]     (from ETC, at the end of last exposure)
+    transparency: current atmospheric transparency [0-1, where 0=total cloud cover]   (from ETC, at the end of last exposure)
 
-        obsplan: filename containing that nights observing plan
-        program (optional): request a tile will be in that program,
-                            otherwise get next field chooses program based on current conditions
+    obsplan: filename containing that nights observing plan
+    program (optional): request a tile will be in that program,
+                        otherwise get next field chooses program based on current conditions
 
-        previoustiles (optional): list of tiles that have been observed that night
+    previoustiles (optional): list of tiles that have been observed that night
 
-  These variables are in the
-        RA _prior:  in degrees, used only for user over-ride, defaults to -99
-        DEC_prior:  in degrees, used only for user over-ride, defaults to -99
-            EFS: for slewing minimization; not used.
+These variables are in the::
 
-  If input values are missing (e.g. first exposure of the night), the NTS falls back to reasonable defaults for skylevel etc.
+    RA _prior:  in degrees, used only for user over-ride, defaults to -99
+    DEC_prior:  in degrees, used only for user over-ride, defaults to -99
+    EFS: for slewing minimization; not used.
 
+If input values are missing (e.g. first exposure of the night), the NTS falls back to reasonable defaults for skylevel etc.
 
-  The primary output of the NTS will be a dictionary with the name of the fiber assign file (full path)
-  The naming convention is fiberassign_<tileid>.fits
 
-  In addition, the following keys/information is returned by the NTS:
-        tileid: (int) DESI Tile ID
-        s2n: (foat) Requested signal to noice (for ETC)
-        foundtile (boolean): indicates whether field selector was successful.
-        exptime: expected exposure time based on ETC information from previous exposure [seconds]
-        maxtime: maximum allowable exposure time [seconds]
+The primary output of the NTS will be a dictionary with the name of the fiber assign file (full path)
+ The naming convention is fiberassign_<tileid>.fits
 
-        Names are converted to FITS convention: TILEID, S2NREQ, EXTTIME, MAXTIME, FBRASSGN
+In addition, the following keys/information is returned by the NTS::
+
+    tileid: (int) DESI Tile ID
+    s2n: (foat) Requested signal to noice (for ETC)
+    foundtile (boolean): indicates whether field selector was successful.
+    exptime: expected exposure time based on ETC information from previous exposure [seconds]
+    maxtime: maximum allowable exposure time [seconds]
+
+Names are converted to FITS convention: TILEID, S2NREQ, EXTTIME, MAXTIME, FBRASSGN
 """
 
 import os