Bug 1714788 - Fixed more Sphinx warnings in 'mach doc' r=sylvestre DONTBUILD

Differential Revision: https://phabricator.services.mozilla.com/D117419

build/docs/supported-configurations.rst

@@ -87,7 +87,7 @@ The term **"Tier-1 platform"** refers to those platforms - CPU
 architectures and operating systems - that are the primary focus of
 Firefox development efforts. Tier-1 platforms are fully supported by
 Mozilla's `continuous integration processes <https://treeherder.mozilla.org/>`__ and the
-:ref:`Try Server`. Any proposed change to Firefox on these
+:ref:`Pushing to Try`. Any proposed change to Firefox on these
 platforms that results in build failures, test failures, performance
 regressions or other major problems **will be reverted immediately**.
 

docs/code-quality/coding-style/coding_style_cpp.rst

@@ -700,7 +700,7 @@ Strings
 -  For 16-bit literal strings, use ``u"..."_ns`` or, if necessary
    ``NS_LITERAL_STRING_FROM_CSTRING(...)`` instead of ``nsAutoString()``
    or other ways that would do a run-time conversion.
-   See :ref:`Avoid runtime conversion of string literals` below.
+   See :ref:`Avoid runtime conversion of string literals <Avoid runtime conversion of string literals>` below.
 -  To compare a string with a literal, use ``.EqualsLiteral("...")``.
 -  Use ``str.IsEmpty()`` instead of ``str.Length() == 0``.
 -  Use ``str.Truncate()`` instead of ``str.SetLength(0)``,
@@ -802,6 +802,7 @@ Free the string manually:
      WarnUser(warning);
      nsMemory::Free(warning);
 
+.. _Avoid runtime conversion of string literals:
 
 Avoid runtime conversion of string literals
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

docs/code-quality/index.rst

@@ -31,7 +31,7 @@ In this document, we try to list these all tools.
    * - Clang-Tidy
      - Yes
      - `bug 712350 <https://bugzilla.mozilla.org/show_bug.cgi?id=712350>`__
-     - :ref:`Static analysis <Mach static analysis>`
+     - :ref:`Static analysis <Static Analysis>`
      - https://clang.llvm.org/extra/clang-tidy/checks/list.html
    * - Clang analyzer
      -

docs/contributing/committing_rules_and_responsibilities.rst

@@ -130,7 +130,7 @@ Failures and backouts
 ---------------------
 
 Patches which cause unit test failures (on :ref:`tier 1
-platforms <Supported build targets>`) will be backed out.
+platforms <Supported Build Hosts and Targets>`) will be backed out.
 Regressions on tier-2 platforms and in performance are not cause for a
 direct backout, but you will be expected to help fix them if quickly.
 

docs/contributing/contribution_quickref.rst

@@ -197,7 +197,7 @@ more information.
     You can ask your reviewer to submit the patch for you if you don't have that
     level of access.
 
-:ref:`More information <Try Server>`
+:ref:`More information <Pushing to Try>`
 
 
 To submit a patch

docs/contributing/debugging/debugging_a_minidump.rst

@@ -115,7 +115,7 @@ build Breakpad, the binary will be at
 path to a Linux minidump will generate a core file on stdout which can
 then be loaded in gdb as usual. You will need to manually download the
 matching Firefox binaries, but then you can use the :ref:`GDB Python
-script <Downloading_symbols_on_Linux_Mac_OS_X>` to download symbols.
+script <Downloading symbols on Linux / Mac OS X>` to download symbols.
 
 The ``minidump-2-core`` source does not currently handle processing
 minidumps from a different CPU architecture than the system it was

docs/contributing/debugging/debugging_on_macos.rst

@@ -53,7 +53,7 @@ try Server Builds
 
 In most cases, developers needing to debug a build as close as possible
 to the production environment should use a :ref:`try
-build <Try Server>`. These
+build <Pushing to Try>`. These
 builds enable Hardened Runtime and only differ from production builds in
 that they are not Notarized which should not otherwise affect
 functionality, (other than the ability to easily launch the browser on

docs/contributing/debugging/stacktrace_report.rst

@@ -94,6 +94,7 @@ Each file in this folder contains one submitted crash report ID. You can
 check the modified or creation time for each file to discern which crash
 reports are relevant to your bug report.
 
+.. _Alternative ways to get a stacktrace:
 
 Alternative ways to get a stacktrace
 ------------------------------------
@@ -105,7 +106,7 @@ will need to obtain a stacktrace manually:
 Windows
 ~~~~~~~
 
-See the article :ref:`Create a stacktrace with Windbg` for information
+See the article :ref:`Create a stacktrace with Windbg <How to get a stacktrace with WinDbg>` for information
 on how to do this.
 
 For a full process dump, see :ref:`How to get a process dump with Windows

docs/contributing/editor.rst

@@ -23,6 +23,8 @@ Visual Studio Code
 
 Go to :doc:`Visual Studio Code <vscode>` dedicated page.
 
+.. _VIM:
+
 VIM
 ---
 
@@ -109,7 +111,7 @@ rtags (LLVM/Clang-based Code Indexing)
 Instructions for the installation of rtags are available at the
 `rtags github repo <https://github.com/Andersbakken/rtags>`__.
 
-rtags requires a :ref:`compilation database <CompileDB back-end / compileflags>`.
+rtags requires a :ref:`compilation database <CompileDB back-end-compileflags>`.
 
 In order for rtags to index correctly, included files need to be copied and
 unified compilation files need to be created. Either run a full build of the
@@ -148,7 +150,7 @@ irony (LLVM/Clang-based Code Completion)
 Instructions on the installation of irony-mode are available at the
 `irony-mode github repo <https://github.com/Sarcasm/irony-mode>`__.
 
-irony-mode requires a :ref:`compilation database <CompileDB back-end / compileflags>`.
+irony-mode requires a :ref:`compilation database <CompileDB back-end-compileflags>`.
 
 Note that irony-mode, by default, uses elisp to parse the
 :code:`compile_commands.json` file. As gecko is a very large codebase, this
@@ -219,6 +221,8 @@ You can run a Visual Studio project by running:
 
     ./mach ide visualstudio
 
+.. _CompileDB back-end-compileflags:
+
 CompileDB back-end / compileflags
 ---------------------------------
 

docs/setup/contributing_code.rst

@@ -72,7 +72,7 @@ We leave this in your hands. Here are some further resources to help:
    `https://developer.mozilla.org/docs/Developer_Guide <https://developer.mozilla.org/docs/Developer_Guide>`_
    and its parent document,
    https://developer.mozilla.org/docs/Mozilla
--  Our :ref:`reviewer checklist <Reviewer_Checklist>` is very
+-  Our :ref:`reviewer checklist <Reviewer Checklist>` is very
    useful, if you have a patch near completion, and seek a favorable
    review
 -  Utilize our build tool :ref:`mach`, its linting,

dom/docs/navigation/nav_replace.rst

@@ -5,7 +5,7 @@ There are 3 major types of navigations, each of which can cause different
 objects to be replaced. The general rules look something like this:
 
 .. csv-table:: objects replaced or preserved across navigations
-   :header: "Class/Id", ":ref:`in-process navigations`", ":ref:`cross-process navigations`", ":ref:`cross-group navigations`"
+   :header: "Class/Id", ":ref:`in-process navigations <in-process navigations>`", ":ref:`cross-process navigations <cross-process navigations>`", ":ref:`cross-group navigations <cross-group navigations>`"
 
    "BrowserId [#bid]_", |preserve|, |preserve|, |preserve|
    "BrowsingContextWebProgress", |preserve|, |preserve|, |preserve|
@@ -43,6 +43,8 @@ objects to be replaced. The general rules look something like this:
 Types of Navigations
 --------------------
 
+.. _in-process navigations:
+
 in-process navigations
 ^^^^^^^^^^^^^^^^^^^^^^
 
@@ -53,6 +55,8 @@ These navigations are used when no process switching or BrowsingContext
 replacement is required, which includes most navigations with Fission
 disabled, and most same site-origin navigations when Fission is enabled.
 
+.. _cross-process navigations:
+
 cross-process navigations
 ^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -66,6 +70,8 @@ These process changes are triggered by ``DocumentLoadListener`` when it
 determines that a process switch is required. See that class's documentation
 for more details.
 
+.. _cross-group navigations:
+
 cross-group navigations
 ^^^^^^^^^^^^^^^^^^^^^^^
 

netwerk/docs/cache2/doc.rst

@@ -19,6 +19,8 @@ be clear directly from the `IDL files <https://searchfox.org/mozilla-central/sea
 -  When there is no profile the new HTTP cache works, but everything is
    stored only in memory not obeying any particular limits.
 
+.. _nsICacheStorageService:
+
 nsICacheStorageService
 ----------------------
 
@@ -29,10 +31,10 @@ nsICacheStorageService
 
 -   \ ``"@mozilla.org/netwerk/cache-storage-service;1"``
 
--  Provides methods accessing "storage" objects – see `nsICacheStorage` below – giving further access to cache entries – see :ref:`nsICacheEntry` more below – per specific URL.
+-  Provides methods accessing "storage" objects – see `nsICacheStorage` below – giving further access to cache entries – see :ref:`nsICacheEntry <nsICacheEntry>` more below – per specific URL.
 
 -  Currently we have 3 types of storages, all the access methods return
-   an :ref:`nsICacheStorage` object:
+   an :ref:`nsICacheStorage <nsICacheStorage>` object:
 
    -  **memory-only** (``memoryCacheStorage``): stores data only in a
       memory cache, data in this storage are never put to disk
@@ -60,14 +62,16 @@ nsICacheStorageService
 
    -  ``purgeFromMemory``– removes (schedules to remove) any
       intermediate cache data held in memory for faster access (more
-      about the :ref:`Intermediate_Memory_Caching` below)
+      about the :ref:`Intermediate_Memory_Caching <Intermediate_Memory_Caching>` below)
+
+.. _nsILoadContextInfo:
 
 nsILoadContextInfo
 ------------------
 
 -  Distinguishes the scope of the storage demanded to open.
 
--  Mandatory argument to ``*Storage`` methods of :ref:`nsICacheStorageService`.
+-  Mandatory argument to ``*Storage`` methods of :ref:`nsICacheStorageService <nsICacheStorageService>`.
 
 -  `nsILoadContextInfo.idl (searchfox) <https://searchfox.org/mozilla-central/source/netwerk/base/nsILoadContextInfo.idl>`_
 
@@ -96,6 +100,7 @@ nsILoadContextInfo
    distinct and cache entries in them do not overlap even when having
    the same URIs.
 
+.. _nsICacheStorage:
 
 nsICacheStorage
 ---------------
@@ -103,7 +108,7 @@ nsICacheStorage
 -  `nsICacheStorage.idl (searchfox) <https://searchfox.org/mozilla-central/source/netwerk/cache2/nsICacheStorage.idl>`_
 
 -  Obtained from call to one of the ``*Storage`` methods on
-   :ref:`nsICacheStorageService`.
+   :ref:`nsICacheStorageService <nsICacheStorageService>`.
 
 -  Represents a distinct storage area (or scope) to put and get cache
    entries mapped by URLs into and from it.
@@ -135,6 +140,8 @@ nsICacheEntryOpenCallback
       (see `bug
       938186 <https://bugzilla.mozilla.org/show_bug.cgi?id=938186>`__).
 
+.. _nsICacheEntry:
+
 nsICacheEntry
 -------------
 
@@ -186,6 +193,8 @@ Lifetime of a new entry
    output stream is closed. This is called :ref:`concurrent
    read/write <Concurrent_read_and_write>`.
 
+.. _Concurrent_read_and_write:
+
 Concurrent read and write
 -------------------------
 
@@ -269,18 +278,18 @@ current scoping model would not be sufficient - use one of the two
 following ways:
 
 #. *[preferred]* Add a new ``<Your>Storage`` method on
-   :ref:`nsICacheStorageService` and if needed give it any arguments to
+   :ref:`nsICacheStorageService <nsICacheStorageService>` and if needed give it any arguments to
    specify the storage scope even more.  Implementation only should need
    to enhance the context key generation and parsing code and enhance
-   current - or create new when needed - :ref:`nsICacheStorage`
+   current - or create new when needed - :ref:`nsICacheStorage <nsICacheStorage>`
    implementations to carry any additional information down to the cache
    service.
 #. *[*\ **not**\ *preferred]* Add a new argument to
-   :ref:`nsILoadContextInfo`; **be careful
+   :ref:`nsILoadContextInfo <nsILoadContextInfo>`; **be careful
    here**, since some arguments on the context may not be known during
    the load time, what may lead to inter-context data leaking or
    implementation problems. Adding more distinction to
-   :ref:`nsILoadContextInfo` also affects all existing storages which may
+   :ref:`nsILoadContextInfo <nsILoadContextInfo>` also affects all existing storages which may
    not be always desirable.
 
 See context keying details for more information.
@@ -325,7 +334,7 @@ Storage and entries scopes
 --------------------------
 
 A *scope key* string used to map the storage scope is based on the
-arguments of :ref:`nsILoadContextInfo`. The form is following (currently
+arguments of :ref:`nsILoadContextInfo <nsILoadContextInfo>`. The form is following (currently
 pending in `bug
 968593 <https://bugzilla.mozilla.org/show_bug.cgi?id=968593>`__):
 
@@ -355,7 +364,7 @@ hashtable are CacheEntry classes, see below.
 
 The hash tables keep a strong reference to ``CacheEntry`` objects. The
 only way to remove ``CacheEntry`` objects from memory is by exhausting a
-memory limit for :ref:`Intermediate_Memory_Caching`, what triggers a background
+memory limit for :ref:`Intermediate_Memory_Caching <Intermediate_Memory_Caching>`, what triggers a background
 process of purging expired and then least used entries from memory.
 Another way is to directly call the
 ``nsICacheStorageService.purge``\ method. That method is also called
@@ -370,7 +379,7 @@ mechanisms ensure thread-safe access and also inability to have more
 then a single instance of a ``CacheEntry`` for a single
 <scope+enhanceID+URL> key.
 
-``CacheStorage``, implementing the :ref:`nsICacheStorage` interface, is
+``CacheStorage``, implementing the :ref:`nsICacheStorage <nsICacheStorage>` interface, is
 forwarding all calls to internal methods of ``CacheStorageService``
 passing itself as an argument.  ``CacheStorageService`` then generates
 the *scope key* using the ``nsILoadContextInfo`` of the storage. Note:
@@ -519,6 +528,8 @@ opening flags.  ``nsICacheStorage.asyncOpenURI`` forwards to
 -  when this is a disk cache entry, its cached data chunks are released
    from memory and only meta data is kept
 
+.. _Intermediate_Memory_Caching:
+
 Intermediate memory caching
 ---------------------------
 

python/mach/docs/usage.rst

@@ -146,6 +146,8 @@ The settings file follows the ``ini`` format, e.g:
     [try]
     default = fuzzy
 
+.. _Adding_mach_to_your_shell:
+
 Adding ``mach`` to your ``PATH``
 --------------------------------
 

services/settings/docs/index.rst

@@ -165,7 +165,7 @@ The provided helper will:
 
     The ``fallbackToDump`` option activates a fallback to a dump that has been
     packaged with the client, when other ways to load the attachment have failed.
-    See :ref:`_services/packaging-attachments` for more information.
+    See :ref:`services/packaging-attachments <services/packaging-attachments>` for more information.
 
 .. note::
 

taskcluster/docs/task-graph.rst

@@ -29,7 +29,7 @@ work?
 All of this is controlled from within the Gecko source code, through a
 process called *task-graph generation*.  This means it's easy to add a
 new job or tweak the parameters of a job in a :ref:`try
-push <Try Server>`, eventually landing
+push <Pushing to Try>`, eventually landing
 that change on an integration branch.
 
 The details of task-graph generation are documented :ref:`in the source

taskcluster/docs/try.rst

@@ -65,7 +65,7 @@ at the root of the source dir. The JSON object in this file contains a
 
 Very simply, this will run any task label that gets passed in as well as their
 dependencies. While it is possible to manually commit this file and push to
-try, it is mainly meant to be a generation target for various :ref:`try server <Try Server>`
+try, it is mainly meant to be a generation target for various :ref:`try server <Pushing to Try>`
 choosers.  For example:
 
 .. parsed-literal::

toolkit/crashreporter/docs/Using_the_Mozilla_symbol_server.rst

@@ -105,6 +105,8 @@ be similar to:
     SYMCHK: FAILED files = 27
     SYMCHK: PASSED + IGNORED files = 60
 
+.. _Downloading symbols on Linux / Mac OS X:
+
 Downloading symbols on Linux / Mac OS X
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~