Merge pull request #269 from sot/docs-pydata

Documentation overhaul

Author: taldcroft

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".

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_"

cheta/derived/mups_valve.py

@@ -30,38 +30,38 @@
 This cleaning technique recovers on average about 90% of data for PM2THV1T.  Since
 2015, about 60% of telemetry is good (no dropout) while 30% is in a recoverable
 fully-dropped state (and 10% is not recoverable).
+::
+
+    def fetch_clean_msid(msid, start, stop=None, dt_thresh=5.0, median=7, model_spec=None,
+                        version=None):
+        Fetch a cleaned version of telemetry for ``msid``.
+
+        If not supplied the model spec will come from
+        ``xija.get_model_spec.get_xija_model_spec(msid, version=version)``
+        (which uses ``$SKA/data/chandra_models/chandra_models/xija/mups_valve/{msid}_spec.json``).
+
+        This function returns a `fetch.Msid` object like a normal fetch but with extra attributes:
+
+        - vals: cleaned telemetry (either original or corrected telemetry, or xija model prediction)
+        - source: label for each vals data point
+        - 0: unrecoverable, so use xija model value
+        - 1: original telemetry
+        - 2: corrected telemetry
+        - vals_raw: raw (uncleaned) telemetry
+        - vals_nan: cleaned telem but with np.nan at points where data are unrecoverable (this is
+                    for plotting)
+        - vals_corr: telemetry with the MUPS correction applied
+        - vals_model: xija model prediction
+
+        :param start: start time
+        :param stop: stop time (default=NOW)
+        :param dt_thresh: tolerance for matching model to data in degF (default=5 degF)
+        :param median: length of median filter (default=7, use 0 to disable)
+        :param model_spec: file name or URL containing relevant xija model spec
+        :param version: version of chandra_models repo (tag, branch, or commit)
+
+        :returns: fetch.Msid object
 
-```
-def fetch_clean_msid(msid, start, stop=None, dt_thresh=5.0, median=7, model_spec=None,
-                     version=None):
-    Fetch a cleaned version of telemetry for ``msid``.
-
-     If not supplied the model spec will come from
-     ``xija.get_model_spec.get_xija_model_spec(msid, version=version)``
-     (which uses ``$SKA/data/chandra_models/chandra_models/xija/mups_valve/{msid}_spec.json``).
-
-    This function returns a `fetch.Msid` object like a normal fetch but with extra attributes:
-
-    - vals: cleaned telemetry (either original or corrected telemetry, or xija model prediction)
-    - source: label for each vals data point
-      - 0: unrecoverable, so use xija model value
-      - 1: original telemetry
-      - 2: corrected telemetry
-    - vals_raw: raw (uncleaned) telemetry
-    - vals_nan: cleaned telem but with np.nan at points where data are unrecoverable (this is
-                for plotting)
-    - vals_corr: telemetry with the MUPS correction applied
-    - vals_model: xija model prediction
-
-    :param start: start time
-    :param stop: stop time (default=NOW)
-    :param dt_thresh: tolerance for matching model to data in degF (default=5 degF)
-    :param median: length of median filter (default=7, use 0 to disable)
-    :param model_spec: file name or URL containing relevant xija model spec
-    :param version: version of chandra_models repo (tag, branch, or commit)
-
-    :returns: fetch.Msid object
-```
 """
 
 import os
@@ -154,6 +154,7 @@ def volts_to_counts(volts):
 
 def get_corr_mups_temp(temp):
     """Calculate a MUPS valve thermistor corrected temperature.
+
     Args:
         temp (float, int): Temperature in Fahrenheit to which a correction will be applied.
 

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
@@ -31,9 +31,29 @@
 )
 from .derived.comps import ComputedMsid
 from .lazy import LazyDict
-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 +129,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
@@ -268,14 +288,14 @@ def _get_start_stop_dates(times):
 ft = pyyaks.context.ContextDict("ft")
 
 # Global (eng_archive) definition of file names
-msid_files = pyyaks.context.ContextDict("msid_files", basedir=ENG_ARCHIVE)
+msid_files = pyyaks.context.ContextDict("msid_files", basedir=remote_access.ENG_ARCHIVE)
 msid_files.update(file_defs.msid_files)
 
 # 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_tbl = ascii.read(os.path.join(DIR_PATH, "filetypes.dat"))
+filetypes_arr = filetypes_tbl.as_array()
 filetypes = np.recarray(len(filetypes_arr), dtype=filetypes_arr.dtype)
 filetypes[()] = filetypes_arr
 
@@ -1830,6 +1850,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)
@@ -2003,16 +2024,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)

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
 ========

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(
         [

cheta/utils.py

@@ -490,7 +490,7 @@ def get_telem_table(
 
 @functools.lru_cache(maxsize=1)
 def get_ofp_states(start, stop):
-    """Get the Onboard Flight Program (OFP) states between ``start`` and ``stop`.
+    """Get the Onboard Flight Program (OFP) states between ``start`` and ``stop``.
 
     This is normally "NRML" but in safe mode it is "SAFE" or other values. State codes:
     ['NNRM' 'STDB' 'STBS' 'NRML' 'NSTB' 'SUOF' 'SYON' 'DPLY' 'SYSF' 'STUP' 'SAFE']

docs/_templates/navbar-project-version.html

@@ -0,0 +1,5 @@
+<a href="{{pathto(root_doc)}}" style="text-decoration: none;">
+    <span style="color: rgb(186, 70, 21); font-size: x-large;">{{project}}</span>
+</a>
+&nbsp;
+<span style="font-size: x-large;">{{ version }}</span>

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 %}