Bug 1400852 - Fix various warnings when building Telemetry in-tree docs. r=chutten
authorAlessio Placitelli <alessio.placitelli@gmail.com>
Wed, 15 Nov 2017 10:20:04 +0100
changeset 436557 5a31594501ba143897ed841c3104c7e5f35e6a0a
parent 436556 15624b327bc410b371f410fd0ce22ddab3308d6d
child 436558 34e43107b2f6ba30504815614c6c769228e62da8
push id117
push userfmarier@mozilla.com
push dateTue, 28 Nov 2017 20:17:16 +0000
reviewerschutten
bugs1400852
milestone59.0a1
Bug 1400852 - Fix various warnings when building Telemetry in-tree docs. r=chutten MozReview-Commit-ID: EksxR3Xwrc5
toolkit/components/telemetry/docs/collection/custom-pings.rst
toolkit/components/telemetry/docs/collection/uptake.rst
toolkit/components/telemetry/docs/data/backgroundhangmonitor-ping.rst
toolkit/components/telemetry/docs/data/core-ping.rst
toolkit/components/telemetry/docs/data/health-ping.rst
toolkit/components/telemetry/docs/data/main-ping.rst
toolkit/components/telemetry/docs/fhr/architecture.rst
toolkit/components/telemetry/docs/fhr/index.rst
toolkit/components/telemetry/docs/internals/preferences.rst
--- a/toolkit/components/telemetry/docs/collection/custom-pings.rst
+++ b/toolkit/components/telemetry/docs/collection/custom-pings.rst
@@ -16,17 +16,17 @@ Custom pings can be submitted from JavaS
    - ``overrideEnvironment`` - a JSON style object that overrides the environment data
 
 ``TelemetryController`` will assemble a ping with the passed payload and the specified options.
 That ping will be archived locally for use with Shield and inspection in ``about:telemetry``.
 If preferences allow the upload of Telemetry pings, the ping will be uploaded at the next opportunity (this is subject to throttling, retry-on-failure, etc.).
 
 .. important::
 
-    Every new data collection in Firefox needs a `data collection review <https://wiki.mozilla.org/Firefox/Data_Collection#Requesting_Approval>`_ from a data collection peer. Just set the feedback? flag for one of the data peers. We try to reply within a business day.
+    Every new data collection in Firefox needs a `data collection review <https://wiki.mozilla.org/Firefox/Data_Collection#Requesting_Approval>`__ from a data collection peer. Just set the feedback? flag for one of the data peers. We try to reply within a business day.
 
 Submission constraints
 ----------------------
 
 When submitting pings on shutdown, they should not be submitted after Telemetry shutdown.
 Pings should be submitted at the latest within:
 
 - the `observer notification <https://developer.mozilla.org/docs/Observer_Notifications#Application_shutdown>`_ ``"profile-before-change"``
@@ -46,17 +46,17 @@ Helpful tools for designing new pings in
 - `gzipServer <https://github.com/mozilla/gzipServer>`_ - a Python script that can run locally and receives and saves Telemetry pings. Making Firefox send to it allows inspecting outgoing pings easily.
 - ``about:telemetry`` - allows inspecting submitted pings from the local archive, including all custom ones.
 
 Designing custom pings
 ======================
 
 In general, creating a new custom ping means you don't benefit automatically from the existing tooling. Further work is needed to make data show up in re:dash or other analysis tools.
 
-In addition to the `data collection review <https://wiki.mozilla.org/Firefox/Data_Collection>`_, questions to guide a new ping design are:
+In addition to the `data collection review <https://wiki.mozilla.org/Firefox/Data_Collection>`__, questions to guide a new ping design are:
 
 - Submission interval & triggers:
    - What events trigger ping submission?
    - What interval is the ping submitted in?
    - Is there a throttling mechanism?
    - What is the desired latency? (submitting "at least daily" still leads to certain latency tails)
    - Are pings submitted on a clock schedule? Or based on "time since session start", "time since last ping" etc.? (I.e. will we get sharp spikes in submission volume?)
 - Size and volume:
--- a/toolkit/components/telemetry/docs/collection/uptake.rst
+++ b/toolkit/components/telemetry/docs/collection/uptake.rst
@@ -5,17 +5,17 @@ Uptake Telemetry
 Firefox continuously pulls data from different remote sources (eg. settings, system add-ons, …). In order to have consistent insights about the *uptake rate* of these *update sources*, our clients can use a unified Telemetry helper to report their *update status*.
 
 The helper — described below — reports predefined update status, which eventually gives a unified way to obtain:
 
 * the proportion of success among clients;
 * its evolution over time;
 * the distribution of error causes.
 
-.. notes::
+.. note::
 
    Examples of update sources: *remote settings, add-ons update, add-ons, gfx, and plugins blocklists, certificate revocation, certificate pinning, system add-ons delivery…*
 
    Examples of update status: *up-to-date, success, network error, server error, signature error, server backoff, unknown error…*
 
 
 Usage
 -----
--- a/toolkit/components/telemetry/docs/data/backgroundhangmonitor-ping.rst
+++ b/toolkit/components/telemetry/docs/data/backgroundhangmonitor-ping.rst
@@ -1,11 +1,11 @@
 
 "backgroundhangmonitor" ping
-==========
+============================
 
 Whenever a thread monitored by the Background Hang Monitor hangs, a stack and
 some non-identifying information about the hang is captured. When 50 of these
 hangs are collected across all processes, or the browser exits, this ping is
 transmitted with the collected hang information.
 
 This ping is only collected in nightly builds, to avoid the high volume of pings
 which would be produced in Beta.
--- a/toolkit/components/telemetry/docs/data/core-ping.rst
+++ b/toolkit/components/telemetry/docs/data/core-ping.rst
@@ -77,17 +77,17 @@ The ``distributionId`` contains the dist
 preferences.json for a given distribution. More information on distributions
 can be found `here <https://wiki.mozilla.org/Mobile/Distribution_Files>`_.
 
 It is optional.
 
 campaignId
 ~~~~~~~~~~~~~~
 The ``campaignId`` contains the campaign identifier like '3ly8t0'.
-It's generated by `Adjust<https://docs.adjust.com/en/tracker-generation/#segmenting-users-dynamically-with-campaign-structure-parameters>`_,
+It's generated by `Adjust <https://docs.adjust.com/en/tracker-generation/#segmenting-users-dynamically-with-campaign-structure-parameters>`_,
 It can only used to identify a campaign, but can't target to a specific user.
 
 It is optional because not everyone has a campaign to begin with.
 
 defaultSearch
 ~~~~~~~~~~~~~
 On Android, this field may be ``null``. To get the engine, we rely on
 ``SearchEngineManager#getDefaultEngine``, which searches in several places in
@@ -151,25 +151,25 @@ Possible value :
 .. code-block:: js
 
     {
        "yahoo.listitem":2,
        "duckduckgo.listitem":1,
        "google-nocodes.suggestion":1
     }
 
-<engine identifier>:
-The identifier of the the search engine. The identifier is collected the way same as desktop.
-we only record the search engine name when :
+**<engine identifier>**: the identifier of the the search engine. The identifier is collected the way same as desktop.
+we only record the search engine name when:
+
 * builtin or suggested search engines with an ID (includes partner search engines in various distribution scenarios).
   If it's not a built-in engine, we show "null" or "other".
 * If the user has "Health Report" and core ping enabled.
 
-<sources>
-It's from one of the 'method's in UI telemetry. Possible values:
+**<sources>**: it's from one of the 'method's in UI telemetry. Possible values:
+
 * actionbar: the user types in the url bar and hits enter to use the default
   search engine
 * listitem: the user selects a search engine from the list of secondary search
   engines at the bottom of the screen
 * suggestion: the user clicks on a search suggestion or, in the case that
   suggestions are disabled, the row corresponding with the main engine
 
 
--- a/toolkit/components/telemetry/docs/data/health-ping.rst
+++ b/toolkit/components/telemetry/docs/data/health-ping.rst
@@ -1,11 +1,11 @@
 
 "health" ping
-============
+=============
 
 This ping is intended to provide data about problems arise when submitting other pings.
 The ping is submitted at most once per hour. On shutdown an additional ping is submitted
 to avoid losing collected data.
 
 This ping is intended to be really small.
 The client id is submitted with this ping.
 
--- a/toolkit/components/telemetry/docs/data/main-ping.rst
+++ b/toolkit/components/telemetry/docs/data/main-ping.rst
@@ -152,29 +152,29 @@ childPayloads
 The Telemetry payloads sent by child processes, recorded on child process shutdown (event ``content-child-shutdown`` observed). They are reduced session payloads, only available with e10s. Among some other things, they don't contain histograms, keyed histograms, add-on details, or UI Telemetry.
 
 Note: Child payloads are not collected and cleared with subsession splits, they are currently only meaningful when analysed from ``saved-session`` or ``main`` pings with ``reason`` set to ``shutdown``.
 
 Note: Before Firefox 51 and bug 1218576, content process histograms and keyedHistograms were in the individual child payloads instead of being aggregated into ``processes.content``.
 
 simpleMeasurements
 ------------------
-This section contains a list of simple measurements, or counters. In addition to the ones highlighted below, Telemetry timestamps (see `here <https://dxr.mozilla.org/mozilla-central/search?q=%22TelemetryTimestamps.add%22&redirect=false&case=true>`_ and `here <https://dxr.mozilla.org/mozilla-central/search?q=%22recordTimestamp%22&redirect=false&case=true>`_) can be reported.
+This section contains a list of simple measurements, or counters. In addition to the ones highlighted below, Telemetry timestamps (see `here <https://dxr.mozilla.org/mozilla-central/search?q=%22TelemetryTimestamps.add%22&redirect=false&case=true>`__ and `here <https://dxr.mozilla.org/mozilla-central/search?q=%22recordTimestamp%22&redirect=false&case=true>`__) can be reported.
 
 totalTime
 ~~~~~~~~~
 A non-monotonic integer representing the number of seconds the session has been alive.
 
 uptime
 ~~~~~~
 A non-monotonic integer representing the number of minutes the session has been alive.
 
 addonManager
 ~~~~~~~~~~~~
-Only available in the extended set of measures, it contains a set of counters related to Addons. See `here <https://dxr.mozilla.org/mozilla-central/search?q=%22AddonManagerPrivate.recordSimpleMeasure%22&redirect=false&case=true>`_ for a list of recorded measures.
+Only available in the extended set of measures, it contains a set of counters related to Addons. See `here <https://dxr.mozilla.org/mozilla-central/search?q=%22AddonManagerPrivate.recordSimpleMeasure%22&redirect=false&case=true>`__ for a list of recorded measures.
 
 UITelemetry
 ~~~~~~~~~~~
 Only available in the extended set of measures. For more see :ref:`uitelemetry`.
 
 startupInterrupted
 ~~~~~~~~~~~~~~~~~~
 A boolean set to true if startup was interrupted by an interactive prompt.
--- a/toolkit/components/telemetry/docs/fhr/architecture.rst
+++ b/toolkit/components/telemetry/docs/fhr/architecture.rst
@@ -1,17 +1,17 @@
 .. _healthreport_architecture:
 
 ============
 Architecture
 ============
 
 ``healthreporter.jsm`` contains the main interface for FHR, the
 ``HealthReporter`` type. An instance of this is created by the
-``data_reporting_service`.
+``data_reporting_service``.
 
 ``providers.jsm`` contains numerous ``Metrics.Provider`` and
 ``Metrics.Measurement`` used for collecting application metrics. If you
 are looking for the FHR probes, this is where they are.
 
 Storage
 =======
 
--- a/toolkit/components/telemetry/docs/fhr/index.rst
+++ b/toolkit/components/telemetry/docs/fhr/index.rst
@@ -4,17 +4,17 @@ Firefox Health Report (Obsolete)
 
 **Firefox Health Report (FHR) is obsolete and no longer ships with Firefox.
 This documentation will live here for a few more cycles.**
 
 Firefox Health Report is a background service that collects application
 metrics and periodically submits them to a central server. The core
 parts of the service are implemented in this directory. However, the
 actual XPCOM service is implemented in the
-``data_reporting_service`.
+``data_reporting_service``.
 
 The core types can actually be instantiated multiple times and used to
 power multiple data submission services within a single Gecko
 application. In other words, everything in this directory is effectively
 a reusable library. However, the terminology and some of the features
 are very specific to what the Firefox Health Report feature requires.
 
 .. toctree::
--- a/toolkit/components/telemetry/docs/internals/preferences.rst
+++ b/toolkit/components/telemetry/docs/internals/preferences.rst
@@ -125,21 +125,21 @@ Preferences
   Allow the ``shutdown`` ping to be sent using the :doc:`ping sender <pingsender>` from the first browsing session.
 
 ``toolkit.telemetry.firstShutdownPing.enabled``
 
   Allow a duplicate of the ``main`` shutdown ping from the first browsing session to be sent as a separate ``first-shutdown`` ping.
 
 ``toolkit.telemetry.newProfilePing.enabled``
 
-  Enable the :doc:`../data/new-profile` ping on new profiles.
+  Enable the :doc:`../data/new-profile-ping` on new profiles.
 
 ``toolkit.telemetry.newProfilePing.delay``
 
-  Controls the delay after which the :doc:`../data/new-profile` is sent on new profiles.
+  Controls the delay after which the :doc:`../data/new-profile-ping` is sent on new profiles.
 
 ``toolkit.telemetry.updatePing.enabled``
 
   Enable the :doc:`../data/update-ping` on browser updates.
 
 Data-choices notification
 -------------------------