DM-11639: Initial Sphinx documentation for pipelines.lsst.io

doc/index.rst

@@ -1,9 +1,10 @@
-.. currentmodule:: lsst.verify.metrics
+####################################
+verify_metrics documentation preview
+####################################
 
-.. _verify_metrics:
+Documentation content:
 
-##########################################################
-lsst.verify.metrics — Metric and specification definitions
-##########################################################
+.. toctree::
+   :maxdepth: 1
 
-TK.
+   verify_metrics/index

doc/manifest.yaml

@@ -0,0 +1,2 @@
+# Documentation manifest
+package: "verify_metrics"

doc/verify_metrics/index.rst

@@ -0,0 +1,53 @@
+.. _verify-metrics-package:
+
+##############
+verify_metrics
+##############
+
+``verify_metrics`` provides centralized metric and specification definitions for the LSST Science Pipelines Verification Framework.
+The :ref:`lsst.verify <lsst.verify>` module uses these metrics and specifications by default.
+
+For background, see the SQR-017_ (design) and SQR-019_ (demo) technotes.
+
+Project info
+============
+
+Repository
+   https://github.com/lsst/verify_metrics
+
+JIRA component
+   `Verification <https://jira.lsstcorp.org/browse/DM/component/14170>`_.
+
+Contributing
+============
+
+Basics
+------
+
+- This repository should only contain metric and specification YAML files.
+  Don't add Python code; instead consider extending the `lsst.verify` API in the :ref:`verify <verify-package>` package.
+
+- Follow `LSST Data Management's workflow <https://developer.lsst.io/processes/workflow.html>`_ for contributions.
+
+Registering metrics
+-------------------
+
+**Metrics** are *measureable things*.
+They can be astronomy concepts (an astrometric RMS) or computational (a task's timing or memory usage).
+
+Metrics that are measured by packages are **registered** here in ``verify_metrics`` by adding or extending a metric definition YAML file in the ``metrics/`` directory.
+See `metrics/README.rst <https://github.com/lsst/verify_metrics/blob/master/metrics/README.rst>`_ for more information.
+
+Registering specifications
+--------------------------
+
+**Specifications** are tests of metric measurements.
+A specification might say that a metric measurement should be less than a certain value if that measurement was made under a certain set of conditions (*provenance*).
+Whenever metrics are measured, DM's SQUASH harness tests those measurements against specifications.
+Depending on the pass/fail outcome, subscribers can receive notifications (alerts).
+
+New specifications are **registered** here in ``verify_metrics`` by adding or extending a specification definition YAML file in the ``specs/`` directory.
+See `specs/README.rst <https://github.com/lsst/verify_metrics/blob/master/specs/README.rst>`_ for more information.
+
+.. _SQR-017: https://sqr-017.lsst.io
+.. _SQR-019: https://sqr-019.lsst.io

metrics/README.rst

@@ -7,6 +7,6 @@ This directory contains *metric definition* YAML files for each EUPS package tha
 Files are named after the EUPS package.
 For example: ``validate_drp.yaml`` for the `validate_drp`_ package.
 
-The format of these YAML files is *currently* documented in https://sqr-017.lsst.io/v/DM-9533/index.html#metric-yaml.
+The format of these YAML files is *currently* documented in https://sqr-017.lsst.io/index.html#metric-yaml.
 
 .. _validate_drp: https://github.com/lsst/validate_drp

specs/README.rst

@@ -7,4 +7,4 @@ Specifications are organized into sub-directories, each named after the correspo
 For a single package, specifications can be distributed across multiple YAML files and even sub-directories.
 The READMEs of each specification sub-directory should state how specifications are organized to suggest where new specifications can be added.
 
-For more information about the format of specification definition YAML files, see https://sqr-017.lsst.io/v/DM-9533/index.html#spec-yaml.
+For more information about the format of specification definition YAML files, see https://sqr-017.lsst.io/index.html#spec-yaml.