Mostly working sphinx-autoapi

sot · Jan 24, 2025 · f5652a8 · f5652a8
1 parent 5abe285
commit f5652a8
Show file tree

Hide file tree

Showing 15 changed files with 183 additions and 126 deletions.
diff --git a/cheta/converters.py b/cheta/converters.py
@@ -434,7 +434,7 @@ def obc4eng(dat):
     At 2014:342:XX:XX:XX, patch PR-361 was applied which transitioned 41 OBA thermistors to
     read out in wide-mode.  After this time the data in the listed OOBTHRxx MSIDs became
     invalid while the OOBTHRxx_WIDE MSIDs became valid.  This converter simply copies the
-    *_WIDE values to the original MSIDs after the time of patch activation.
+    ``*_WIDE`` values to the original MSIDs after the time of patch activation.
 
     At 2017:312:16:11:16, patch PR-411 was applied which transitioned 6 OBA thermistors to
     wide-mode and these were added below as patch "c".

diff --git a/cheta/derived/__init__.py b/cheta/derived/__init__.py
@@ -1,7 +1,6 @@
 # Licensed under a 3-clause BSD style license - see LICENSE.rst
 """
 Derived Parameters
-------------------
 
 The engineering archive has pseudo-MSIDs that are derived via computation from
 telemetry MSIDs.  All derived parameter names begin with the characters "DP_"

diff --git a/cheta/fetch.py b/cheta/fetch.py
@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 # Licensed under a 3-clause BSD style license - see LICENSE.rst
 """
-Fetch values from the Ska engineering telemetry archive.
+Fetch values from the cheta telemetry archive.
 """
 
 import collections
@@ -34,6 +34,27 @@
 from .remote_access import ENG_ARCHIVE
 from .units import Units
 
+__all__ = [
+    "data_source",
+    "local_or_remote_function",
+    "get_units",
+    "set_units",
+    "read_bad_times",
+    "msid_glob",
+    "MSID",
+    "MSIDset",
+    "Msid",
+    "Msidset",
+    "HrcSsMsid",
+    "memoized",
+    "get_time_range",
+    "get_telem",
+    "add_logging_handler",
+    "get_data_gap_spec_parser",
+    "msid_matches_data_gap_spec",
+    "create_msid_data_gap",
+]
+
 # Module-level units, defaults to CXC units (e.g. Kelvins etc)
 UNITS = Units(system="cxc")
 
@@ -109,7 +130,7 @@ def set(cls, *data_sources):
         """
         Set current data sources.
 
-        :param *data_sources: one or more sources (str)
+        :param data_sources: one or more sources (str)
         """
         if any(
             data_source.split()[0] not in cls._allowed for data_source in data_sources
@@ -274,8 +295,8 @@ def _get_start_stop_dates(times):
 # Module-level values defining available content types and column (MSID) names.
 # Then convert from astropy Table to recarray for API stability.
 # Note that filetypes.as_array().view(np.recarray) does not quite work...
-filetypes = ascii.read(os.path.join(DIR_PATH, "filetypes.dat"))
-filetypes_arr = filetypes.as_array()
+__filetypes = ascii.read(os.path.join(DIR_PATH, "filetypes.dat"))
+filetypes_arr = __filetypes.as_array()
 filetypes = np.recarray(len(filetypes_arr), dtype=filetypes_arr.dtype)
 filetypes[()] = filetypes_arr
 
@@ -1832,6 +1853,7 @@ def write_zip(self, filename):
 class Msid(MSID):
     """
     Fetch data from the engineering telemetry archive into an MSID object.
+
     Same as MSID class but with filter_bad=True by default.
 
     :param msid: name of MSID (case-insensitive)
@@ -2005,16 +2027,16 @@ def get_telem(
     High-level routine to get telemetry for one or more MSIDs and perform
     common processing functions:
 
-      - Fetch a set of MSIDs over a time range, specifying the sampling as
-        either full-resolution, 5-minute, or daily data.
-      - Filter out bad or missing data.
-      - Interpolate (resample) all MSID values to a common uniformly-spaced time sequence.
-      - Remove or select time intervals corresponding to specified Kadi event types.
-      - Change the time format from CXC seconds (seconds since 1998.0) to something more
-        convenient like GRETA time.
-      - Write the MSID telemetry data to a zipfile.
+    - Fetch a set of MSIDs over a time range, specifying the sampling as
+      either full-resolution, 5-minute, or daily data.
+    - Filter out bad or missing data.
+    - Interpolate (resample) all MSID values to a common uniformly-spaced time sequence.
+    - Remove or select time intervals corresponding to specified Kadi event types.
+    - Change the time format from CXC seconds (seconds since 1998.0) to something more
+      convenient like GRETA time.
+    - Write the MSID telemetry data to a zipfile.
 
-    :param msids: MSID(s) to fetch (string or list of strings)')
+    :param msids: MSID(s) to fetch (string or list of strings)
     :param start: Start time for data fetch (default=<stop> - 30 days)
     :param stop: Stop time for data fetch (default=NOW)
     :param sampling: Data sampling (full | 5min | daily) (default=full)
@@ -2286,8 +2308,7 @@ def create_msid_data_gap(msid_obj: MSID, data_gap_spec: str):
         start = CxoTime(args.start)
         stop = CxoTime(args.stop)
         logger.info(
-            f"Creating data gap for {msid_obj.MSID} "
-            f"from {start.date} to {stop.date}"
+            f"Creating data gap for {msid_obj.MSID} from {start.date} to {stop.date}"
         )
         i0, i1 = np.searchsorted(msid_obj.times, [start.secs, stop.secs])
         for attr in msid_obj.colnames:

diff --git a/cheta/get_telem.py b/cheta/get_telem.py
@@ -1,6 +1,6 @@
 # Licensed under a 3-clause BSD style license - see LICENSE.rst
 """
-Fetch telemetry from the Ska engineering archive.
+Fetch telemetry from the cheta archive.
 
 Examples
 ========

diff --git a/cheta/units.py b/cheta/units.py
@@ -149,12 +149,17 @@ def FASTEP_to_mm(vals, delta_val=False):
 
 def mm_to_FASTEP(vals, delta_val=False):
     """
-    # compute mm from simulated integral step values and invert the CXC calibration
-    # given below:
-    x = np.arange(-5000.0, 0.0)  # step
-    y = (1.47906994e-3  *   x +  3.5723322e-8 *   x**2 +  -1.08492544e-12  *   x**3 +
-         3.9803832e-17  *   x**4 +  5.29336e-21  *  x**5 +  1.020064e-25  *   x**6)
-    r = np.polyfit(y, x, 8)
+    Convert from mm to focus assembly steps.
+
+    ::
+
+        # compute mm from simulated integral step values and invert the CXC calibration
+        # given below:
+        x = np.arange(-5000.0, 0.0)  # step
+        y = (1.47906994e-3  *   x +  3.5723322e-8 *   x**2 +  -1.08492544e-12  *   x**3 +
+            3.9803832e-17  *   x**4 +  5.29336e-21  *  x**5 +  1.020064e-25  *   x**6)
+        r = np.polyfit(y, x, 8)
+
     """
     r = np.array(
         [

diff --git a/docs/_templates/python/module.rst b/docs/_templates/python/module.rst
@@ -0,0 +1,126 @@
+{% if obj.display %}
+   {% if is_own_page %}
+{{ obj.id }}
+{{ "=" * obj.id|length }}
+
+.. py:module:: {{ obj.name }}
+
+      {% if obj.docstring %}
+.. autoapi-nested-parse::
+
+   {{ obj.docstring|indent(3) }}
+
+      {% endif %}
+
+      {% block submodules %}
+         {% set visible_subpackages = obj.subpackages|selectattr("display")|list %}
+         {% set visible_submodules = obj.submodules|selectattr("display")|list %}
+         {% set visible_submodules = (visible_subpackages + visible_submodules)|sort %}
+         {% if visible_submodules %}
+Submodules
+----------
+
+.. toctree::
+   :maxdepth: 1
+
+            {% for submodule in visible_submodules %}
+   {{ submodule.include_path }}
+            {% endfor %}
+
+
+         {% endif %}
+      {% endblock %}
+      {% block content %}
+         {% set visible_children = obj.children|selectattr("display")|list %}
+         {% if visible_children %}
+
+            {% set visible_exceptions = visible_children|selectattr("type", "equalto", "exception")|list %}
+            {% if visible_exceptions %}
+               {% if "exception" in own_page_types or "show-module-summary" in autoapi_options %}
+Exceptions
+----------
+
+                  {% if "exception" in own_page_types %}
+.. toctree::
+   :hidden:
+
+                     {% for exception in visible_exceptions %}
+   {{ exception.include_path }}
+                     {% endfor %}
+
+                  {% endif %}
+.. autoapisummary::
+
+                  {% for exception in visible_exceptions %}
+   {{ exception.id }}
+                  {% endfor %}
+               {% endif %}
+
+
+            {% endif %}
+            {% set visible_classes = visible_children|selectattr("type", "equalto", "class")|list %}
+            {% if visible_classes %}
+               {% if "class" in own_page_types or "show-module-summary" in autoapi_options %}
+Classes
+-------
+
+                  {% if "class" in own_page_types %}
+.. toctree::
+   :hidden:
+
+                     {% for klass in visible_classes %}
+   {{ klass.include_path }}
+                     {% endfor %}
+
+                  {% endif %}
+.. autoapisummary::
+
+                  {% for klass in visible_classes %}
+   {{ klass.id }}
+                  {% endfor %}
+               {% endif %}
+
+
+            {% endif %}
+            {% set visible_functions = visible_children|selectattr("type", "equalto", "function")|list %}
+            {% if visible_functions %}
+               {% if "function" in own_page_types or "show-module-summary" in autoapi_options %}
+Functions
+---------
+
+                  {% if "function" in own_page_types %}
+.. toctree::
+   :hidden:
+
+                     {% for function in visible_functions %}
+   {{ function.include_path }}
+                     {% endfor %}
+
+                  {% endif %}
+.. autoapisummary::
+
+                  {% for function in visible_functions %}
+   {{ function.id }}
+                  {% endfor %}
+               {% endif %}
+
+
+            {% endif %}
+            {% set this_page_children = visible_children|rejectattr("type", "in", own_page_types)|list %}
+
+         {% endif %}
+      {% endblock %}
+   {% else %}
+.. py:module:: {{ obj.name }}
+
+      {% if obj.docstring %}
+   .. autoapi-nested-parse::
+
+      {{ obj.docstring|indent(6) }}
+
+      {% endif %}
+      {% for obj_item in visible_children %}
+   {{ obj_item.render()|indent(3) }}
+      {% endfor %}
+   {% endif %}
+{% endif %}
diff --git a/docs/api/comps.rst b/docs/api/comps.rst
diff --git a/docs/api/derived.rst b/docs/api/derived.rst
diff --git a/docs/api/fetch.rst b/docs/api/fetch.rst
diff --git a/docs/api/index.rst b/docs/api/index.rst
diff --git a/docs/api/plot.rst b/docs/api/plot.rst
diff --git a/docs/api/utils.rst b/docs/api/utils.rst
diff --git a/docs/conf.py b/docs/conf.py
@@ -30,8 +30,7 @@
     "sphinx_copybutton",
     "matplotlib.sphinxext.plot_directive",
     "numpydoc",
-    "sphinx_automodapi.automodapi",
-    "sphinx_automodapi.smart_resolver",
+    "autoapi.extension",
 ]
 
 templates_path = ["_templates"]
@@ -98,9 +97,9 @@
     "numpy": ("http://docs.scipy.org/doc/numpy/", None),
 }
 
-automodapi_inheritance_diagram = False
-automodapi_toctreedirnm = "_api"
-# autosummary_generate = True
-# autosummary_imported_members = False
-
-toc_object_entries = False
+autoapi_dirs = ["../cheta"]
+autoapi_root = "api"
+autoapi_template_dir = "_templates"
+autoapi_own_page_level = "function"
+autoapi_ignore = ["*/test*.py", "*/fetch_old.py", "setup.py"]
+suppress_warnings = ["autoapi.python_import_resolution"]