[doc only] Bug 1703280: Move metric parameter docs to the Glean Book (#303)

* [doc only] Bug 1703280: Move metric parameter docs to the Glean Book

* Move metric parameter URL

Author: mdboom

README.md

@@ -4,13 +4,14 @@ Parser tools for Mozilla's Glean telemetry.
 
 ## Features
 
-Parses the `metrics.yaml` files for the Glean telemetry SDK and produces
-output for various integrations.
+Contains various utilities for handling `metrics.yaml` and `pings.yaml` for [the
+Glean SDK](https://mozilla.github.io/glean). This includes producing generated
+code for various integrations, linting and coverage testing.
 
 ## Documentation
 
-The full documentation is available
-[here](https://mozilla.github.io/glean_parser/).
+- [User documentation for Glean](https://mozilla.github.io/glean/).
+- [`glean_parser` developer documentation](https://mozilla.github.io/glean_parser/).
 
 ## Requirements
 

docs/conf.py

@@ -32,7 +32,7 @@
 
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = ['sphinx.ext.autodoc', 'sphinx.ext.viewcode', 'sphinxext.eval', 'recommonmark']
+extensions = ['sphinx.ext.autodoc', 'sphinx.ext.viewcode', 'recommonmark']
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']

docs/index.rst

@@ -3,6 +3,9 @@ Glean parser
 
 .. image:: _static/glean.jpeg
 
+This contains the developer documentation for `glean_parser`. Information about
+using Glean is available in [the Glean book](https://mozilla.github.io/glean).
+
 .. toctree::
    :maxdepth: 2
    :caption: Contents:

docs/metrics-yaml.rst

@@ -1,56 +1,7 @@
 ``metrics.yaml`` file
 =====================
 
-The ``metrics.yaml`` file defines what metrics and events your application will
-collect.
-
-The top-level of the file must contain the following key-value pair to indicate
-that it is a Glean ``metrics.yaml`` file::
-
-   $schema: moz://mozilla.org/schemas/glean/metrics/2-0-0
-
-The other keys at the top level of the file are category names. Category names
-must be in ``snake_case``, but may also contain ``.`` to indicate *ad hoc*
-subcategories. Category names have a maximum of 40 characters.
-
-Within each category, the individual metrics are defined. The key is the name of
-the metric (``snake_case`` with a maximum of 30 characters), and each value is
-an object with the following parameters described below.
-
-``metrics.yaml`` files must be encoded in UTF-8.
-
-Metric parameters
------------------
-
-.. metric_parameter:: type
-
-.. metric_parameter:: description
-
-.. metric_parameter:: notification_emails
-
-.. metric_parameter:: bugs
-
-.. metric_parameter:: data_reviews
-
-.. metric_parameter:: lifetime
-
-.. metric_parameter:: send_in_pings
-
-.. metric_parameter:: disabled
-
-.. metric_parameter:: expires
-
-.. metric_parameter:: version
-
-.. metric_parameter:: time_unit
-
-.. metric_parameter:: labels
-
-.. metric_parameter:: extra_keys
-
-.. metric_parameter:: gecko_datapoint
-
-.. metric_parameter:: no_lint
+Documentation for the ``metrics.yaml`` file has moved to `metrics parameters in the Glean user documentation <https://mozilla.github.io/glean/book/user/metric-parameters.html>`_.
 
 JSON Schema
 -----------

docs/pings-yaml.rst

@@ -1,33 +1,7 @@
 ``pings.yaml`` file
 ===================
 
-The ``pings.yaml`` file defines what pings your application will collect.
-
-The top-level of the file must contain the following key-value pair to indicate
-that it is a Glean ``pings.yaml`` file::
-
-   $schema: moz://mozilla.org/schemas/glean/pings/2-0-0
-
-The other keys at the top level of the file are ping names.
-Ping names must be in ``kebab-case``.
-Ping names have a maximum of 30 characters.
-
-Ping parameters
----------------
-
-.. ping_parameter:: description
-
-.. ping_parameter:: include_client_id
-
-.. ping_parameter:: send_if_empty
-
-.. ping_parameter:: notification_emails
-
-.. ping_parameter:: bugs
-
-.. ping_parameter:: data_reviews
-
-.. ping_parameter:: reasons
+Documentation for the ``pings.yaml`` file has moved to `custom pings in the Glean user documentation <https://mozilla.github.io/glean/book/user/pings/custom.html>`_.
 
 JSON Schema
 -----------

docs/sphinxext/eval.py

@@ -107,6 +107,11 @@ definitions:
               properties: `range_min`, `range_max`, `bucket_count`,
               `histogram_type`.
 
+            - `rate`: Used to record the rate something happens relative to some
+              other thing. For example, the number of HTTP connections that
+              experience an error relative to the number of total HTTP
+              connections made.
+
             - Additionally, labeled versions of many metric types are supported.
               These support the `labels`_ parameter, allowing multiple instances
               of the metric to be stored at a given set of labels. The labeled

glean_parser/schemas/metrics.1-0-0.schema.yaml

@@ -105,6 +105,11 @@ definitions:
               properties: `range_min`, `range_max`, `bucket_count`,
               `histogram_type`.
 
+            - `rate`: Used to record the rate something happens relative to some
+              other thing. For example, the number of HTTP connections that
+              experience an error relative to the number of total HTTP
+              connections made.
+
             - Additionally, labeled versions of many metric types are supported.
               These support the `labels`_ parameter, allowing multiple instances
               of the metric to be stored at a given set of labels. The labeled