Bug 1648959 - Done internal linking in docs in toolkit Directory,DONTBUILD.r=championshuttler
authorchocos <kandpalnehu@gmail.com>
Tue, 30 Jun 2020 22:26:40 +0000
changeset 538122 9e5effc60b13d3531f529d06d7e76e0da5701185
parent 538121 f0e47b29f8c4840d9f9fbe971991f86179b55314
child 538123 8042b7b369435bf8c17d0b2d9af65aabb0a966ac
push id37558
push userdluca@mozilla.com
push dateWed, 01 Jul 2020 09:30:12 +0000
treeherdermozilla-central@e950bdd669d4 [default view] [failures only]
perfherder[talos] [build metrics] [platform microbench] (compared to previous push)
reviewerschampionshuttler
bugs1648959
milestone80.0a1
first release with
nightly linux32
nightly linux64
nightly mac
nightly win32
nightly win64
last release without
nightly linux32
nightly linux64
nightly mac
nightly win32
nightly win64
Bug 1648959 - Done internal linking in docs in toolkit Directory,DONTBUILD.r=championshuttler Differential Revision: https://phabricator.services.mozilla.com/D81464
toolkit/components/normandy/docs/data-collection.rst
toolkit/components/telemetry/docs/collection/histograms.rst
toolkit/components/telemetry/docs/collection/scalars.rst
toolkit/components/telemetry/docs/internals/review.rst
toolkit/components/telemetry/docs/start/report-gecko-telemetry-in-glean.rst
--- a/toolkit/components/normandy/docs/data-collection.rst
+++ b/toolkit/components/normandy/docs/data-collection.rst
@@ -117,31 +117,28 @@ reported under the key ``normandy/recipe
 
 .. data:: RECIPE_SIGNATURE_INVALID
 
    :Telemetry value: signature_error
 
    Normandy failed to verify the signature of the recipe.
 
 
-Additionally, Normandy reports a `keyed scalar`_ to measure recipe
+Additionally, Normandy reports a :ref:`keyed scalar <Scalars>` to measure recipe
 freshness. This scalar is called ``normandy.recipe_freshness``, and it
 corresponds to the ``last_modified`` date of each recipe (using its ID
 as the key), reported as seconds since 1970 in UTC.
 
-.. _keyed scalar: https://firefox-source-docs.mozilla.org/toolkit/components/telemetry/telemetry/collection/scalars.html
-
 
 Enrollment
 -----------
 Normandy records enrollment and unenrollment of users into studies, and
-records that data using `Telemetry Events`_. All data is stored in the
+records that data using :ref:`Telemetry Events <eventtelemetry>`. All data is stored in the
 ``normandy`` category.
 
-.. _Telemetry Events: https://firefox-source-docs.mozilla.org/toolkit/components/telemetry/telemetry/collection/events.html
 
 Enrollment IDs
 ^^^^^^^^^^^^^^
 
 Most Normandy telemetry carries an *enrollment ID*. These IDs are generated
 when Normandy enrolls the client in a change, be it a study, rollout, or
 something else. These enrollment IDs are used for the lifetime of that
 change, and are only used for that change (not shared between similar
--- a/toolkit/components/telemetry/docs/collection/histograms.rst
+++ b/toolkit/components/telemetry/docs/collection/histograms.rst
@@ -225,16 +225,18 @@ Optional. This is one of:
 
 .. warning::
 
     Because they are collected by default, opt-out probes need to meet a higher "user benefit" threshold than opt-in probes during data collection review.
 
 
     Every new or changed data collection in Firefox needs a `data collection review <https://wiki.mozilla.org/Firefox/Data_Collection>`__ from a Data Steward.
 
+.. _histogram-products:
+
 ``products``
 -------------
 Required. This field is a list of products this histogram can be recorded on. Currently-supported values are:
 
 - ``firefox`` - Collected in Firefox Desktop for submission via Firefox Telemetry.
 - ``fennec`` - Collected in Firefox for Android for submission via Firefox Mobile Telemetry.
 
 ``record_into_store``
--- a/toolkit/components/telemetry/docs/collection/scalars.rst
+++ b/toolkit/components/telemetry/docs/collection/scalars.rst
@@ -79,16 +79,19 @@ Example:
       kind: Ci.nsITelemetry.SCALAR_TYPE_COUNT,
       keyed: false,
       record_on_release: false
     },
   });
   // Now scalars can be recorded.
   Services.telemetry.scalarSet("myAddon.category.counter_scalar", 37);
 
+
+.. _scalars-c++-API:
+
 C++ API
 -------
 Probes in native code can use the more convenient helper functions declared in `Telemetry.h <https://dxr.mozilla.org/mozilla-central/source/toolkit/components/telemetry/core/Telemetry.h>`_:
 
 .. code-block:: cpp
 
     void ScalarAdd(mozilla::Telemetry::ScalarID aId, uint32_t aValue);
     void ScalarSet(mozilla::Telemetry::ScalarID aId, uint32_t aValue);
@@ -146,16 +149,18 @@ A probe can be defined as follows:
         bug_numbers:
           - 1276190
         description: A nice one-line description.
         expires: never
         kind: uint
         notification_emails:
           - telemetry-client-dev@mozilla.com
 
+.. _scalars-required-fields:
+
 Required Fields
 ---------------
 
 - ``bug_numbers``: A list of unsigned integers representing the number of the bugs the probe was introduced in.
 - ``description``: A single or multi-line string describing what data the probe collects and when it gets collected.
 - ``expires``: The version number in which the scalar expires, e.g. "30"; a version number of type "N" is automatically converted to "N.0a1" in order to expire the scalar also in the development channels. A telemetry probe acting on an expired scalar will print a warning into the browser console. For scalars that never expire the value ``never`` can be used.
 - ``kind``: A string representing the scalar type. Allowed values are ``uint``, ``string`` and ``boolean``.
 - ``notification_emails``: A list of email addresses to notify with alerts of expiring probes. More importantly, these are used by the data steward to verify that the probe is still useful.
@@ -188,17 +193,17 @@ Optional Fields
    - ``unix``
    - ``all`` (record on all operating systems)
 
 String type restrictions
 ------------------------
 To prevent abuses, the content of a string scalar is limited to 50 characters in length. Trying
 to set a longer string will result in an error and no string being set.
 
-.. _scalars.keyed-scalars:
+.. _scalars-keyed-scalars:
 
 Keyed Scalars
 -------------
 Keyed scalars are collections of ``uint`` or ``boolean`` scalar types, indexed by a string key that can contain UTF8 characters and cannot be longer than 72 characters. Keyed scalars can contain up to 100 keys. This scalar type is for example useful when you want to break down certain counts by a name, like how often searches happen with which search engine.
 
 Keyed ``string`` scalars are not supported.
 
 Keyed scalars should only be used if the set of keys are not known beforehand. If the keys are from a known set of strings, other options are preferred if suitable, like categorical histograms or splitting measurements up into separate scalars.
--- a/toolkit/components/telemetry/docs/internals/review.rst
+++ b/toolkit/components/telemetry/docs/internals/review.rst
@@ -75,17 +75,17 @@ Considerations for all changes
 
 - Sanity checking:
 
   - How does this behave in a release build? Have you tested this?
   - Does this change contain test coverage? We require test coverage for every new code, changes and bug fixes.
 
 - Does this need documentation updates?
 
-  - To the `in-tree docs <https://firefox-source-docs.mozilla.org/toolkit/components/telemetry/telemetry/>`_?
+  - To the :ref:`in-tree docs <Telemetry>`?
   - To the `firefox-data-docs <https://docs.telemetry.mozilla.org/>`_ (`repository <https://github.com/mozilla/firefox-data-docs>`_)?
   - To the `glean documentation <https://github.com/mozilla-mobile/android-components/tree/master/components/service/glean>`_?
 
 - Following up:
 
   - Do we have a validation bug filed yet?
   - Do all TODOs have follow-up bugs filed?
   - Do we need to communicate this to our users?
--- a/toolkit/components/telemetry/docs/start/report-gecko-telemetry-in-glean.rst
+++ b/toolkit/components/telemetry/docs/start/report-gecko-telemetry-in-glean.rst
@@ -19,17 +19,17 @@ The ``engine-gecko-*`` components provid
 
 Reporting an existing histogram
 ===============================
 Exfiltrating existing histograms is a relatively straightforward process made up of a few small steps.
 
 Tag histograms in ``Histograms.json``
 -------------------------------------
 Accumulations to non-tagged histograms are ignored if streaming Telemetry is enabled.
-To tag a histogram you must add the `geckoview_streaming` product to the `products list <https://firefox-source-docs.mozilla.org/toolkit/components/telemetry/telemetry/collection/histograms.html#products>`__  in the `Histograms.json file <https://hg.mozilla.org/mozilla-central/file/tip/toolkit/components/telemetry/Histograms.json>`__ .
+To tag a histogram you must add the `geckoview_streaming` product to the :ref:`products list <histogram-products>`  in the `Histograms.json file <https://hg.mozilla.org/mozilla-central/file/tip/toolkit/components/telemetry/Histograms.json>`__ .
 
 Add Glean metrics to ``metrics.yaml``
 -------------------------------------
 The Glean SDK provides a number of `higher level metric types <https://mozilla.github.io/glean/book/user/metrics/index.html>`__ to map Gecko histogram metrics to.
 However, Gecko histograms lack the metadata to infer the Glean SDK destination type manually.
 For this reason, engineers must pick the most appropriate Gecko SDK type themselves.
 
 Read more about how to add Glean SDK metrics to the `metrics.yaml file <https://hg.mozilla.org/mozilla-central/file/tip/toolkit/components/telemetry/geckoview/streaming/metrics.yaml>`__ in the `Glean SDK documentation <https://mozilla.github.io/glean/book/user/adding-new-metrics.html>`__.
@@ -156,17 +156,17 @@ Similar definitions can be used for the 
 
 Reporting a scalar
 ==================
 Exfiltrating existing boolean, string or uint scalars, or adding new ones, is a relatively straightforward process made up of a few small steps.
 
 Tag scalars in ``Scalars.yaml``
 ----------------------------------
 Accumulations to non-tagged scalars are ignored if streaming Telemetry is enabled.
-To tag a scalar you must add the `geckoview_streaming` product to the `products list <https://firefox-source-docs.mozilla.org/toolkit/components/telemetry/collection/scalars.html#required-fields>`__  in the `Scalars.yaml file <https://hg.mozilla.org/mozilla-central/file/tip/toolkit/components/telemetry/Scalars.yaml>`__ .
+To tag a scalar you must add the `geckoview_streaming` product to the :ref:`products list <scalars-required-fields>`  in the `Scalars.yaml file <https://hg.mozilla.org/mozilla-central/file/tip/toolkit/components/telemetry/Scalars.yaml>`__ .
 
 Add Glean metrics to ``metrics.yaml``
 -------------------------------------
 The Glean SDK provides the `Quantity <https://mozilla.github.io/glean/book/user/metrics/quantity.html>`__, `Boolean <https://mozilla.github.io/glean/book/user/metrics/boolean.html>`__ and `String <https://mozilla.github.io/glean/book/user/metrics/string.html>`__ metric types to map Gecko scalars to.
 However, Gecko scalars lack the metadata to infer the Glean SDK destination type manually.
 For this reason, engineers must pick the most appropriate Gecko SDK type themselves.
 
 Read more about how to add Glean SDK metrics to the `metrics.yaml file <https://hg.mozilla.org/mozilla-central/file/tip/toolkit/components/telemetry/geckoview/streaming/metrics.yaml>`__ in the `Glean SDK documentation <https://mozilla.github.io/glean/book/user/adding-new-metrics.html>`__.
@@ -249,11 +249,11 @@ 4. Use the Glean SDK `debugging features
 .. note::
 
     It is important to substitute GeckoView in Android Components, even if it's possible to substitute it directly in the final product. This is because the bulk of the processing happens in Android Components, in the `engine-gecko-*` components wrapping GeckoView.
 
 Unsupported features
 ====================
 This is the list of the currently unsupported features:
 
-* `keyed scalars <https://firefox-source-docs.mozilla.org/toolkit/components/telemetry/collection/scalars.html#keyed-scalars>`__ are not supported and there are no future plans for supporting them;
-* uint scalar operations other than `set <https://firefox-source-docs.mozilla.org/toolkit/components/telemetry/collection/scalars.html#id2>`__ are not supported and there are no future plans for supporting them.
-* `events <https://firefox-source-docs.mozilla.org/toolkit/components/telemetry/collection/events.html>`__ are not supported and there are no future plans for supporting them.
+* :ref:`keyed scalars <scalars-keyed-scalars>` are not supported and there are no future plans for supporting them;
+* uint scalar operations other than :ref:`set <scalars-c++-API>` are not supported and there are no future plans for supporting them.
+* :ref:`events <eventtelemetry>` are not supported and there are no future plans for supporting them.