NO BUG - Fix reStructuredText warnings

Sphinx has been complaining about a number of reStructuredText warnings
for a while. Fix all the ones in .rst files.

Not asking for review because this is docs only and changing .rst files
can't break anything important.

DONTBUILD (NPOTB)

browser/base/content/docs/sslerrorreport/dataformat.rst

@@ -1,4 +1,4 @@
-.. _healthreport_dataformat:
+.. _sslerrorreport_dataformat:
 
 ==============
 Payload Format

browser/base/content/docs/sslerrorreport/index.rst

@@ -1,4 +1,4 @@
-.. _sslerrorreport
+.. _sslerrorreport:
 
 ===================
 SSL Error Reporting

browser/docs/UITelemetry.rst

@@ -6,7 +6,7 @@ UI Telemetry sends its data as a JSON blob. This document describes the differen
 of the JSON blob.
 
 ``toolbars``
-------------
+============
 
 This tracks the state of the user's UI customizations. It has the following properties:
 
@@ -34,15 +34,16 @@ This tracks the state of the user's UI customizations. It has the following prop
 - ``countableEvents`` - please refer to the next section.
 - ``durations`` - an object mapping descriptions to duration records, which records the amount of
   time a user spent doing something. Currently only has one property:
-   - ``customization`` - how long a user spent customizing the browser. This is an array of
-     objects, where each object has a ``duration`` property indicating the time in milliseconds,
-     and a ``bucket`` property indicating a bucket in which the duration info falls.
+
+  - ``customization`` - how long a user spent customizing the browser. This is an array of
+    objects, where each object has a ``duration`` property indicating the time in milliseconds,
+    and a ``bucket`` property indicating a bucket in which the duration info falls.
 
 
 .. _UITelemetry_countableEvents:
 
 ``countableEvents``
--------------------
+===================
 
 Countable events are stored under the ``toolbars`` section. They count the number of times certain
 events happen. No timing or other correlating information is stored - purely the number of times
@@ -66,23 +67,27 @@ Each bucket is an object with the following properties:
   or ``other``, depending on the kind of item clicked. Note that this is not tracked on OS X, where
   we can't listen for these events because of the global menubar.
 - ``click-bookmarks-menu-button`` is also similar, with the item IDs being replaced by:
-   - ``menu`` for clicks on the 'menu' part of the item;
-   - ``add`` for clicks that add a bookmark;
-   - ``edit`` for clicks that open the panel to edit an existing bookmark;
-   - ``in-panel`` for clicks when the button is in the menu panel, and clicking it does none of the
+
+  - ``menu`` for clicks on the 'menu' part of the item;
+  - ``add`` for clicks that add a bookmark;
+  - ``edit`` for clicks that open the panel to edit an existing bookmark;
+  - ``in-panel`` for clicks when the button is in the menu panel, and clicking it does none of the
      above;
 - ``customize`` tracks different types of customization events without the ``left``, ``middle`` and
   ``right`` distinctions. The different events are the following, with each storing a count of the
   number of times they occurred:
-   - ``start`` counts the number of times the user starts customizing;
-   - ``add`` counts the number of times an item is added somewhere from the palette;
-   - ``move`` counts the number of times an item is moved somewhere else (but not to the palette);
-   - ``remove`` counts the number of times an item is removed to the palette;
-   - ``reset`` counts the number of times the 'restore defaults' button is used;
+
+  - ``start`` counts the number of times the user starts customizing;
+  - ``add`` counts the number of times an item is added somewhere from the palette;
+  - ``move`` counts the number of times an item is moved somewhere else (but not to the palette);
+  - ``remove`` counts the number of times an item is removed to the palette;
+  - ``reset`` counts the number of times the 'restore defaults' button is used;
 - ``search`` is an object tracking searches of various types, keyed off the search
     location, storing a number indicating how often the respective type of search
     has happened.
+
   - There are also two special keys that mean slightly different things.
+
     - ``urlbar-keyword`` records searches that would have been an invalid-protocol
       error, but are now keyword searches.  They are also counted in the ``urlbar``
       keyword (along with all the other urlbar searches).
@@ -93,7 +98,8 @@ Each bucket is an object with the following properties:
 
 
 ``UITour``
-----------
+==========
+
 The UITour API provides ways for pages on trusted domains to safely interact with the browser UI and request it to perform actions such as opening menus and showing highlights over the browser chrome - for the purposes of interactive tours. We track some usage of this API via the ``UITour`` object in the UI Telemetry output.
 
 Each page is able to register itself with an identifier, a ``Page ID``. A list of Page IDs that have been seen over the last 8 weeks is available via ``seenPageIDs``.
@@ -107,7 +113,8 @@ Page IDs are also used to identify buckets for :ref:`UITelemetry_countableEvents
 
 
 ``contextmenu``
----------------
+===============
+
 We track context menu interactions to figure out which ones are most often used and/or how
 effective they are. In the ``contextmenu`` object, we first store things per-bucket. Next, we
 divide the following different context menu situations:

build/docs/defining-binaries.rst

@@ -21,6 +21,8 @@ are no conflicting variables in those source files.
 ``SOURCES`` and ``UNIFIED_SOURCES`` are lists which must be appended to, and
 each append requires the given list to be alphanumerically ordered.
 
+.. code-block:: python
+
    UNIFIED_SOURCES += [
        'FirstSource.cpp',
        'SecondSource.cpp',
@@ -41,6 +43,8 @@ Static Libraries
 To build a static library, other than defining the source files (see above), one
 just needs to define a library name with the ``Library`` template.
 
+.. code-block:: python
+
    Library('foo')
 
 The library file name will be ``libfoo.a`` on UNIX systems and ``foo.lib`` on
@@ -50,12 +54,16 @@ If the static library needs to aggregate other static libraries, a list of
 ``Library`` names can be added to the ``USE_LIBS`` variable. Like ``SOURCES``, it
 requires the appended list to be alphanumerically ordered.
 
+.. code-block:: python
+
    USE_LIBS += ['bar', 'baz']
 
 If there are multiple directories containing the same ``Library`` name, it is
 possible to disambiguate by prefixing with the path to the wanted one (relative
 or absolute):
 
+.. code-block:: python
+
    USE_LIBS += [
        '/path/from/topsrcdir/to/bar',
        '../relative/baz',
@@ -82,6 +90,8 @@ required libraries to ``USE_LIBS`` for the bigger one, it is possible to tell
 the build system that the library built in the current directory is meant to
 be linked to that bigger library, with the ``FINAL_LIBRARY`` variable.
 
+.. code-block:: python
+
    FINAL_LIBRARY = 'xul'
 
 The ``FINAL_LIBRARY`` value must match a unique ``Library`` name somewhere
@@ -98,6 +108,8 @@ Sometimes, we want shared libraries, a.k.a. dynamic libraries. Such libraries
 are defined similarly to static libraries, using the ``SharedLibrary`` template
 instead of ``Library``.
 
+.. code-block:: python
+
    SharedLibrary('foo')
 
 When this template is used, no static library is built. See further below to
@@ -113,6 +125,8 @@ systems.
 On OSX, one may want to create a special kind of dynamic library: frameworks.
 This is done with the ``Framework`` template.
 
+.. code-block:: python
+
    Framework('foo')
 
 With a ``Framework`` name of ``foo``, the framework file name will be ``foo``.
@@ -126,6 +140,8 @@ Executables
 Executables, a.k.a. programs, are, in the simplest form, defined with the
 ``Program`` template.
 
+.. code-block:: python
+
    Program('foobar')
 
 On UNIX systems, the executable file name will be ``foobar``, while on Windows,
@@ -138,6 +154,8 @@ names.
 In some cases, we want to create an executable per source file in the current
 directory, in which case we can use the ``SimplePrograms`` template
 
+.. code-block:: python
+
    SimplePrograms([
        'FirstProgram',
        'SecondProgram',
@@ -148,6 +166,8 @@ Contrary to ``Program``, which requires corresponding ``SOURCES``, when using
 corresponding ``sources`` have an extension different from ``.cpp``, it is
 possible to specify the proper extension:
 
+.. code-block:: python
+
    SimplePrograms([
        'ThirdProgram',
        'FourthProgram',
@@ -170,6 +190,8 @@ Programs and libraries usually need to link with system libraries, such as a
 widget toolkit, etc. Those required dependencies can be given with the
 ``OS_LIBS`` variable.
 
+.. code-block:: python
+
    OS_LIBS += [
        'foo',
        'bar',
@@ -182,6 +204,8 @@ For convenience with ``pkg-config``, ``OS_LIBS`` can also take linker flags
 such as ``-L/some/path`` and ``-llib``, such that it is possible to directly
 assign ``LIBS`` variables from ``CONFIG``, such as:
 
+.. code-block:: python
+
    OS_LIBS += CONFIG['MOZ_PANGO_LIBS']
 
 (assuming ``CONFIG['MOZ_PANGO_LIBS']`` is a list, not a string)
@@ -201,6 +225,8 @@ path (like when disambiguating identical ``Library`` names). The same naming
 rules apply as other uses of ``USE_LIBS``, so only the library name without
 prefix and suffix shall be given.
 
+.. code-block:: python
+
    USE_LIBS += [
        '/path/from/topsrcdir/to/third-party/bar',
        '../relative/third-party/baz',
@@ -217,6 +243,8 @@ Building both static and shared libraries
 When both types of libraries are required, one needs to set both
 ``FORCE_SHARED_LIB`` and ``FORCE_STATIC_LIB`` boolean variables.
 
+.. code-block:: python
+
    FORCE_SHARED_LIB = True
    FORCE_STATIC_LIB = True
 
@@ -227,6 +255,8 @@ than the name given to the ``Library`` template.
 The ``STATIC_LIBRARY_NAME`` and ``SHARED_LIBRARY_NAME`` variables can be used
 to change either the static or the shared library name.
 
+.. code-block:: python
+
   Library('foo')
   STATIC_LIBRARY_NAME = 'foo_s'
 
@@ -236,6 +266,8 @@ With the above, on Windows, ``foo_s.lib`` will be the static library,
 In some cases, for convenience, it is possible to set both
 ``STATIC_LIBRARY_NAME`` and ``SHARED_LIBRARY_NAME``. For example:
 
+.. code-block:: python
+
   Library('mylib')
   STATIC_LIBRARY_NAME = 'mylib_s'
   SHARED_LIBRARY_NAME = CONFIG['SHARED_NAME']
@@ -248,6 +280,8 @@ When refering to a ``Library`` name building both types of libraries in
 it is wanted to link the static version, in which case the ``Library`` name
 needs to be prefixed with ``static:`` in ``USE_LIBS``
 
+::
+
    a/moz.build:
       Library('mylib')
       FORCE_SHARED_LIB = True
@@ -272,6 +306,8 @@ linking to a library with a ``SONAME``, the resulting library or program will
 have a dependency on the library with the name corresponding to the ``SONAME``
 instead of the ``Library`` name. This only impacts ELF systems.
 
+::
+
    a/moz.build:
       Library('mylib')
    b/moz.build:

mobile/android/base/docs/uitelemetry.rst

@@ -72,7 +72,7 @@ Events capture key occurrences. They should be brief and simple, and should not
   The time at which the event occurred. If not specified, this field defaults to the current value of the realtime clock.
 
 Versioning
-========
+==========
 
 As a we improve on our Telemetry methods, it is foreseeable that our probes will change over time. Different versions of a probe could carry different data or have different interpretations on the server-side. To make it easier for the server to handle these changes, you should add version numbers to your event and session names. An example of a versioned session is ``homepanel.1``; this is version 1 of the ``homepanel`` session. This approach should also be applied to event names, an example being: ``panel.enable.1`` and ``panel.enable.2``.
 

services/cloudsync/docs/dataformat.rst

@@ -1,8 +1,8 @@
 .. _cloudsync_dataformat:
 
-=========
+===========
 Data Format
-=========
+===========
 
 All fields are required unless noted otherwise.
 

services/docs/metrics.rst

@@ -13,7 +13,7 @@ Overview
 The Metrics framework by itself doesn't do much: it simply provides a
 generic mechanism for collecting and persisting data. It is up to users
 of this framework to drive collection and do something with the obtained
-data. A consumer of this framework is :ref:`firefox_health_report`.
+data. A consumer of this framework is :ref:`healthreport`.
 
 Relationship to Telemetry
 -------------------------

services/healthreport/docs/dataformat.rst

@@ -668,7 +668,7 @@ Example
     }
 
 org.mozilla.addons.plugins
--------------------------
+--------------------------
 
 This measurement contains information about the currently-installed plugins.
 
@@ -697,7 +697,7 @@ directly from ``nsIPluginTag`` via ``nsIPluginHost``.
 *updateDay* is the number of days since UNIX epoch of the plugins last modified
 time.
 *mimeTypes* is the list of mimetypes the plugin supports, see
-``nsIPluginTag.getMimeTypes()`.
+``nsIPluginTag.getMimeTypes()``.
 
 Example
 ^^^^^^^

toolkit/components/crashes/docs/crash-events.rst

@@ -75,7 +75,7 @@ There should be ``UUID.dmp`` and ``UUID.extra`` files on disk, saved by
 Breakpad.
 
 crash.submission.1
-^^^^^^^^^^^^
+^^^^^^^^^^^^^^^^^^
 
 This event is produced when a crash is submitted.
 

toolkit/modules/docs/AsyncShutdown.rst

@@ -8,9 +8,10 @@ During shutdown of the process, subsystems are closed one after another. ``Async
 - services and their clients;
 - shutdown phases (e.g. profile-before-change) and their clients.
 
-.. _AsyncShutdown Barriers:
+.. _AsyncShutdown_Barriers:
+
 Barriers: Expressing shutdown dependencies towards a service
-==========================================
+============================================================
 
 Consider a service FooService. At some point during the shutdown of the process, this service needs to:
 - inform its clients that it is about to shut down;
@@ -22,7 +23,7 @@ This may be expressed as an instance of ``AsyncShutdown.Barrier``. An instance o
 - methods for the owner of the barrier to let it consult the state of blockers and wait until all client-registered blockers have been resolved.
 
 Shutdown timeouts
-------------------
+-----------------
 
 By design, an instance of ``AsyncShutdown.Barrier`` will cause a crash
 if it takes more than 60 seconds `awake` for its clients to lift or
@@ -34,11 +35,12 @@ which it can neither proceed with shutdown nor be relaunched.
 If the CrashReporter is enabled, this crash will report:
 - the name of the barrier that failed;
 - for each blocker that has not been released yet:
+
   - the name of the blocker;
   - the state of the blocker, if a state function has been provided (see :ref:`AsyncShutdown.Barrier.state`).
 
 Example 1: Simple Barrier client
-----------------------------
+--------------------------------
 
 The following snippet presents an example of a client of FooService that has a shutdown dependency upon FooService. In this case, the client wishes to ensure that FooService is not shutdown before some state has been reached. An example is clients that need write data asynchronously and need to ensure that they have fully written their state to disk before shutdown, even if due to some user manipulation shutdown takes place immediately.
 
@@ -58,7 +60,7 @@ The following snippet presents an example of a client of FooService that has a s
     // we have reached the expected state
 
 Example 2: Simple Barrier owner
-----------------------------
+-------------------------------
 
 The following snippet presents an example of a service FooService that
 wishes to ensure that all clients have had a chance to complete any
@@ -91,10 +93,10 @@ outstanding operations before FooService shuts down.
 
 Frequently, a service that owns a ``AsyncShutdown.Barrier`` is itself a client of another Barrier.
 
-.. _AsyncShutdown.Barrier.prototype.state:
+.. _AsyncShutdown.Barrier.state:
 
 Example 3: More sophisticated Barrier client
---------------------------------------
+--------------------------------------------
 
 The following snippet presents FooClient2, a more sophisticated client of FooService that needs to perform a number of operations during shutdown but before the shutdown of FooService. Also, given that this client is more sophisticated, we provide a function returning the state of FooClient2 during shutdown. If for some reason FooClient2's blocker is never lifted, this state can be reported as part of a crash report.
 
@@ -141,7 +143,7 @@ The following snippet presents FooClient2, a more sophisticated client of FooSer
 
 
 Example 4: A service with both internal and external dependencies
--------------------------------------------------------
+-----------------------------------------------------------------
 
  .. code-block:: javascript
 
@@ -211,10 +213,10 @@ Example 4: A service with both internal and external dependencies
       // ...
     });
 
+.. _AsyncShutdown_phases:
 
-.. _AsyncShutdown phases:
 Phases: Expressing dependencies towards phases of shutdown
-===========================================
+==========================================================
 
 The shutdown of a process takes place by phase, such as:
 - ``profileBeforeChange`` (once this phase is complete, there is no guarantee that the process has access to a profile directory);
@@ -255,5 +257,3 @@ List of phases
   The client capability for clients wishing to block asynchronously
   during observer notification "web-workers-shutdown". Once the phase
   is complete, clients MUST NOT use web workers.
-
-

toolkit/modules/docs/index.rst

@@ -1,6 +1,6 @@
-==============
+===============
 Toolkit modules
-==============
+===============
 
 The ``/toolkit/modules`` directory contains a number of self-contained toolkit modules considered small enough that they do not deserve individual directories.