Bug 961146 - Refactor Health Report documentation, import external docs; r=rnewman

FHR docs were extracted from /services/docs into their own compartment.
This arguably should have been done originally.

Documentation on the payload format has been imported from
https://github.com/mozilla-services/docs. Those docs were created in a
time before we had in-tree docs and this tree is a more logical home for
them.

--HG--
rename : services/docs/healthreport.rst => services/healthreport/docs/index.rst
extra : rebase_source : 4e2fd62cc98ea2620f580e34d032cb39bafb5108
extra : amend_source : bd6309cc9d53aba1b085067960bf20a94125c5b0

services/docs/index.rst

@@ -7,12 +7,11 @@ features that communicate with external services - hence its name.
 
 It was originally created to hold code for Firefox Sync. Later, it
 became the location for code written by the Mozilla Services Client team
-and thus includes Firefox Health Report. This team no longer exists, but
+and thus includes :ref:`healthreport`. This team no longer exists, but
 the directory remains.
 
 .. toctree::
    :maxdepth: 1
 
    metrics
-   healthreport
    datareporting

services/healthreport/docs/architecture.rst

@@ -1,24 +1,6 @@
-.. _firefox_health_report:
-
-=====================
-Firefox Health Report
-=====================
-
-``/services/healthreport`` contains the implementation of the
-``Firefox Health Report`` (FHR).
-
-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
-:ref:`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.
+.. _healthreport_architecture:
 
+============
 Architecture
 ============
 
@@ -31,7 +13,7 @@ Architecture
 are looking for the FHR probes, this is where they are.
 
 Storage
--------
+=======
 
 Firefox Health Report stores data in 3 locations:
 
@@ -42,13 +24,13 @@ Firefox Health Report stores data in 3 locations:
 * Lesser state and run-time options are stored in preferences.
 
 Preferences
------------
+===========
 
 Preferences controlling behavior of Firefox Health Report live in the
 ``datareporting.healthreport.*`` branch.
 
 Service and Data Control
-^^^^^^^^^^^^^^^^^^^^^^^^
+------------------------
 
 The follow preferences control behavior of the service and data upload.
 
@@ -112,7 +94,7 @@ to analyze! Keep in mind that Firefox Health Report can be useful even
 if it's not submitting data to remote servers!
 
 Logging
-^^^^^^^
+-------
 
 The following preferences allow you to control the logging behavior of
 Firefox Health Report.
@@ -138,7 +120,7 @@ logging.dumpLevel
    ``dump()``.
 
 State
-^^^^^
+-----
 
 currentDaySubmissionFailureCount
    How many submission failures the client has encountered while
@@ -239,12 +221,3 @@ want storage to be robust. We originally stored UUIDs in preferences,
 which only flush to disk periodically. Writes to preferences were
 apparently getting lost. We switched to writing directly to files to
 eliminate this window.
-
-Legal and Privacy Concerns
-==========================
-
-Because Firefox Health Report collects and submits data to remote
-servers and is an opt-out feature, there are legal and privacy
-concerns over what data may be collected and submitted. **Additions or
-changes to submitted data should be signed off by responsible
-parties.**

services/healthreport/docs/index.rst

@@ -0,0 +1,35 @@
+.. _healthreport:
+
+=====================
+Firefox Health Report
+=====================
+
+``/services/healthreport`` contains the implementation of the
+``Firefox Health Report`` (FHR).
+
+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
+:ref:`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::
+   :maxdepth: 1
+
+   architecture
+   dataformat
+
+Legal and Privacy Concerns
+==========================
+
+Because Firefox Health Report collects and submits data to remote
+servers and is an opt-out feature, there are legal and privacy
+concerns over what data may be collected and submitted. **Additions or
+changes to submitted data should be signed off by responsible
+parties.**

services/healthreport/moz.build

@@ -4,6 +4,8 @@
 # License, v. 2.0. If a copy of the MPL was not distributed with this
 # file, You can obtain one at http://mozilla.org/MPL/2.0/.
 
+SPHINX_TREES['healthreport'] = 'docs'
+
 TEST_DIRS += ['tests']
 
 EXTRA_COMPONENTS += [