Merge pull request #7 from ehsteve/cmad-docs

Major update to template, Adding Doc templates and stub functions

.devcontainer/requirements.txt

@@ -1,12 +1,15 @@
-astropy>=4.1.0
 numpy>=1.16.0
-flake8
-black
+astropy>=4.1.0
+sunpy
+git+https://github.com/HERMES-SOC/hermes_core/
+flake8 # for code style
+black # for code style
 tox
-pytest
+pytest # for testing
 pytest-astropy
 pytest-cov
-sphinx
-sphinx-automodapi
-towncrier
-ipython
+pre-commit
+sphinx # for documentation
+sphinx-automodapi # for documentation
+towncrier # for building changelog for documentation
+ipython # for easier debugging

.github/workflows/testing.yml

@@ -16,7 +16,7 @@ jobs:
       fail-fast: false
       matrix:
         platform: [ubuntu-latest, macos-latest, windows-latest]
-        python-version: [3.6, 3.7, 3.8, 3.9]
+        python-version: [3.7, 3.8, 3.9]
 
     steps:
     - uses: actions/checkout@v2
@@ -29,7 +29,7 @@ jobs:
         python -m pip install --upgrade pip
         python -m pip install -e .[test]
     - name: Run tests
-      run: pytest --pyargs hermes_instrument/tests --cov hermes_instrument
+      run: pytest --pyargs hermes_instrument --cov hermes_instrument
       env:
         PLATFORM: ${{ matrix.platform }}
 

CITATION.rst

@@ -0,0 +1,16 @@
+Acknowledging this Package
+==========================
+
+If you use Package in your scientific work, we would appreciate citing it in your publications.
+Proper citations and acknowledgement is key to a healthy scientific community and enables scientific reproducibility.
+
+Citing in Publications
+----------------------
+
+Please add the following line within your methods, conclusion or acknowledgements sections:
+
+   *This research used version X.Y.Z (software citation) of the Hermes Instrument open source
+   software package (paper citation).*
+
+The software citation should be the specific Zenodo DOI for the version used in your work.
+A paper citation does not yet exist.

LICENSE.rst

@@ -1,25 +1 @@
-Copyright (c) 2021, Jane Doe
-All rights reserved.
-
-Redistribution and use in source and binary forms, with or without modification,
-are permitted provided that the following conditions are met:
-
-* Redistributions of source code must retain the above copyright notice, this
-  list of conditions and the following disclaimer.
-* Redistributions in binary form must reproduce the above copyright notice, this
-  list of conditions and the following disclaimer in the documentation and/or
-  other materials provided with the distribution.
-* Neither the name of the Astropy Team nor the names of its contributors may be
-  used to endorse or promote products derived from this software without
-  specific prior written permission.
-
-THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
-ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
-WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
-DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
-ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
-(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
-LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
-ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
-(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
-SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+See license/LICENSE.rst

README.rst

@@ -8,7 +8,7 @@ Overview
     :stub-columns: 1
 
     * - docs
-      - |docs|
+      - |docs| |readtehdocs|
     * - build status
       - |testing| |codestyle|
 
@@ -24,6 +24,10 @@ Overview
     :target: https://github.com/HERMES-SOC/hermes_instrument/actions/workflows/codestyle.yml
     :alt: Codestyle and linting using flake8
 
+.. |readthedocs| .. image:: https://readthedocs.org/projects/nasa-hermes-instrument/badge/?version=latest
+    :target: https://nasa-hermes-instrument.readthedocs.io/en/latest/?badge=latest
+    :alt: Documentation Status
+
 .. end-badges
 
 

docs/about.rst

@@ -0,0 +1 @@
+.. include:: ../CITATION.rst

docs/api.rst

@@ -0,0 +1,9 @@
+.. _reference:
+
+*************
+API Reference
+*************
+
+.. automodapi:: hermes_instrument
+.. automodapi:: hermes_instrument.calibration.calibration
+.. automodapi:: hermes_instrument.io.file_tools

docs/cmad/calibration_plan.rst

@@ -0,0 +1,47 @@
+.. _calibration_plan:
+
+**********************************
+<Instrument name> Calibration Plan
+**********************************
+
+Overall Calibration Scheme
+==========================
+This section summarizes the calibration philosophy and identifies any heritage tied to the
+calibration schemes of related missions and instruments.
+
+Pre-flight Calibration Plans
+============================
+This section details how unit level (e.g., individual detectors) and system level (e.g., instrument
+subsystem) are tested and calibrated to verify that they will meet the expected performance
+parameters prior to placement (i.e., launch) into the relevant operational environment.
+
+<Subsystem name> Pre-flight Calibrations
+----------------------------------------
+This subsection describes the specific testing and examination methods used to
+characterize the build and performance of each subsystem or component (e.g., diffraction
+gratings, CCDs)
+
+Instrument Description
+======================
+This subsection describes the primary scientific objectives of the instrument, its hardware,
+physical configuration, etc. This subsection lists the major elements of the instrument and
+provides a schematic of the conceptual design. Known issues due to external factors that
+could impact any long-term comparison or analysis (e.g., optical distortion due to gradual
+radiation degradation) should be captured.
+
+In-flight Tracking of Short-Term Changes
+========================================
+This section identifies any potential factors in the operational environment (e.g., radiation,
+temperature fluctuations, exposure-related degradation) that could eventually result in off-
+nominal changes in the instrument’s measurements. The methods used to identify and track
+these changes are also described.
+
+Long-term Absolute Calibration Tracking (Re-Calibration)
+========================================================
+This section identifies any periodic re-calibration to absolute standards to be used over the
+course of the mission.
+
+Validation
+==========
+This describes the use of any other measurements (via complementary instruments) or models
+to validate the instrument’s measurements

docs/cmad/index.rst

@@ -0,0 +1,13 @@
+*****************************************************
+Calibration and Measurement Algorithm Document (CMAD)
+*****************************************************
+
+.. toctree::
+   :numbered:
+   :maxdepth: 1
+
+   scope
+   related_docs
+   overview_and_bkg
+   calibration_plan
+   measurement_algos

docs/cmad/measurement_algos.rst

@@ -0,0 +1,42 @@
+.. _measurement_algos:
+
+***************************************************
+<Instrument name> Measurement Algorithm Description
+***************************************************
+
+Theoretical basis
+=================
+This section provides context and background information for the quantity or phenomenon
+being detected. The algorithms and techniques used are described, with pertinent equations
+and references included. Logical groupings (i.e., separate subsections) may be used for clarity of
+the concepts introduced.
+
+Conversion of Instrument Signals to <Measurable units>
+======================================================
+
+Measurement Equations
+---------------------
+This subsection (one for each subsystem) describes the equations used to derive measurable
+quantities from raw instrument signals.
+
+Signal Estimates and Error Analyses for Subsystems
+==================================================
+
+<Subsystem name> Signal Estimates and Error Analysis
+----------------------------------------------------
+This subsection (one for each subsystem) provides details on the expected signal values for
+the instrument subsystem. This can be expressed graphically. A table summarizing the
+“acceptable” values—that is, the minimum values that would meet mission requirements
+and be deemed still usable to meet the mission’s science objectives—as well as the
+estimated uncertainty in the measured values and the error budget allowable for each
+parameter may be included. The equations for determining the uncertainties should be
+included.
+
+Preflight Calibration Algorithms
+================================
+This section describes the process for calibrating the instrument prior to shipment and/or
+installation. It may refer back to measurement equations detailed earlier in the document and
+identify the specific variables being solved for in order to determine proper calibration.
+
+Appendix A. List of Variable Definitions
+========================================

docs/cmad/overview_and_bkg.rst

@@ -0,0 +1,58 @@
+.. _overview_and_bkg:
+
+***********************************
+Overview and Background Information
+***********************************
+
+This section briefly summarizes the instrument and its objectives to provide its role and importance
+within the context of the SMD portfolio.
+
+Science Objectives
+==================
+
+This section describes the science objective(s) of the mission.
+
+<Instrument name> Instrument Description
+========================================
+
+
+Measurement Concept
+===================
+This subsection summarizes the instrument parameters and associated requirements that must
+be fulfilled to attain mission success. The types of measurements or observations made as well
+as how the instrument executes those measurements are described. A table like the example
+below may be included.
+
++----------------+----------------------------+--------------------------------+--------------+
+| Parameter      | Minimum Success Criteria   | Comprehensive Success Criteria | Design Goals |
++================+============================+================================+==============+
+| Wavelength     | 6 or more emissions to     | 0.1-105 nm                     | 0.1-105 nm   |
+| :math:`\lambda`| specify the chromosphere,  |                                |              |
+|                | TR, and corona, plus the   |                                |              |
+|                | He II 30.4 nm emission     |                                |              |             
++----------------+----------------------------+--------------------------------+--------------+
+| Time Cadence   |                     60 sec |                    < 20 sec    |       10 sec |
++----------------+----------------------------+--------------------------------+--------------+
+
+Instrument Subsystem Descriptions
+=================================
+
+<Subsystem name>
+----------------
+This section (and any necessary subsections) provides details on the susbsystems or components
+responsible for directly obtaining the measurements or observations pertinent to the instrument. Details
+on the layout and design of the subsystem, examples of expected measurements, and interactions with
+any other subsystems should be provided.
+
+<Instrument name> Heritage
+--------------------------
+
+Subsystem Heritage
+^^^^^^^^^^^^^^^^^^
+This section summarizes any heritage from past missions for the instrument and its subsystems or
+components (e.g., detectors, cameras, signal processing electronics).
+
+Algorithm and Calibration Heritage
+""""""""""""""""""""""""""""""""""
+This section identifies any heritage from past missions for the algorithms used to process/convert detector
+signals into the measurable quantities needed to meet the science requirements.

docs/cmad/related_docs.rst

@@ -0,0 +1,29 @@
+.. _related_docs:
+
+**********************
+Related Documentations
+**********************
+
+Applicable Documents
+--------------------
+
+This section identifies (in tabular format) any other project/mission documentation with higher-
+level guiding requirements or that provide more detail or context. See example below:
+
+.. list-table::
+    :widths: 50 25 50
+    :header-rows: 1
+
+    * - Title
+      - Document Number
+      - Publication Date
+    * - `Heliophysics Division Science Data Management Policy <https://science.nasa.gov/science-pink/s3fs-public/atoms/files/HPD%20Data%20Policy_Final_20220209.pdf>`_
+      - HPD-SDMP 
+      - 14 Feb 2022
+    * - HERMES Project Level Requirement Appendix (PLRA)   
+      - HERMES-SYS-REQ-0027 
+      - 13 Oct 2021 
+    * - `HERMES Project Data Management Plan (PDMP) <https://github.com/HERMES-SOC/hermes-pdmp>`_
+      - HERMES-MGMT-PLAN-0015
+      - 7 Oct 2021
+

docs/cmad/scope.rst

@@ -0,0 +1,8 @@
+.. _scope:
+
+*****
+Scope
+*****
+
+This section provides a brief description of the specific aspects of instrument calibration covered by
+this plan

docs/conf.py

@@ -30,6 +30,7 @@
     "sphinx.ext.autodoc",
     "sphinx.ext.intersphinx",
     "sphinx.ext.todo",
+    "sphinx.ext.autosummary",
     "sphinx.ext.coverage",
     "sphinx.ext.inheritance_diagram",
     "sphinx.ext.viewcode",
@@ -40,8 +41,15 @@
     "sphinx_automodapi.smart_resolver",
 ]
 
+# Set automodapi to generate files inside the generated directory
+# automodapi_toctreedirnm = "_build/html/api"
+numpydoc_show_class_members = False
+# generate autosummary even if no references
+autosummary_generate = True
+autosummary_imported_members = True
+
 # Add any paths that contain templates here, relative to this directory.
-# templates_path = ['_templates']
+templates_path = ["_templates"]
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
@@ -87,13 +95,14 @@
     ),
     "astropy": ("http://docs.astropy.org/en/stable/", None),
     "sunpy": ("https://docs.sunpy.org/en/stable/", None),
+    "hermes_core": ("https://hermes-core.readthedocs.io/en/latest/", None),
 }
 
 # -- Options for HTML output -------------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-html_theme = "nature"
+html_theme = "bizstyle"
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,