Bug 1665854 - fx doc: Various improvements + configuration + fixes in the doc r=firefox-build-system-reviewers,rstewart

Depends on D90831

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

docs/contributing/debugging/debugging_a_minidump.rst

@@ -31,9 +31,9 @@ access and where to find minidump files for crash reports, consult the
 Using the MS Visual Studio debugger
 -----------------------------------
 
-#. Set up the debugger to `use the Mozilla symbol
-   server <https://developer.mozilla.org/en/Using_the_Mozilla_symbol_server>`__ and `source
-   server <https://developer.mozilla.org/en-US/docs/Mozilla/Using_the_Mozilla_source_server>`__\.
+#. Set up the debugger to :ref:`use the Mozilla symbol
+   server <Using The Mozilla Symbol Server>` and
+   :ref:`source server <Using The Mozilla Source Server>`.
 #. Double-click on the minidump file to open it in the debugger.
 #. When it loads, click the green icon in the visual studio debugger
    toolbar that looks like a play button.

docs/contributing/debugging/understanding_crash_reports.rst

@@ -317,8 +317,7 @@ See also
 -  `A talk about understanding crash
    reports <https://air.mozilla.org/a-talk-about-understanding-crash-reports/>`__,
    by David Baron, from March 2016.
--  `A guide to searching crash
-   reports <https://developer.mozilla.org/en-US/docs/A_guide_to_searching_crash_reports>`__
+-  :ref:`A guide to searching crash reports`
 
 .. |Example fields in the "Details" tab of a crash report| image:: https://mdn.mozillademos.org/files/13579/Details1.png
 .. |Information relating to bug reports in the "Details" tab of a crash report| image:: https://mdn.mozillademos.org/files/13581/Details2.png

docs/crash-reporting/index.rst

@@ -20,44 +20,33 @@ Crash data submitted using the Mozilla Crash Reporter is located on
 a specific crash that you submitted, you first need to find the Crash ID
 that the server has assigned your crash. Type ``about:crashes`` into
 your location bar to get a page listing both submitted and unsubmitted
-crash reports. For more information, see `How to get a stacktrace for a
-bug report </en-US/docs/How_to_get_a_stacktrace_for_a_bug_report>`__.
+crash reports. For more information, see :ref:`How to get a stacktrace for a bug report`.
 
 
 Reports and queries
 -------------------
 
 crash-stats has built-in reports of "topcrashes" for each release
-grouped by signature. There is also a custom query tool which allows
-users to limit searches on more precise information.
+grouped by signature. There is also a `custom query tool <https://crash-stats.mozilla.org/search/>`__
+which allows users to limit searches on more precise information.
 
 Finally, a set of Mozilla employees have access to directly query the
 underlying data in either SQL summary or using mapreduce on the storage
-cluster. If you are interested in obtaining this advanced access,
-contact `Gabriele Svelto <mailto:gsvelto@mozilla.com>`__.
+cluster. If you are interested in obtaining this advanced access, read
+`Crash Stats Documentation: Protected Data Access <https://crash-stats.mozilla.org/documentation/protected_data_access/>`__
 
 
 See also
 --------
 
--  `Understanding crash
-   reports </en-US/docs/Mozilla/Projects/Crash_reporting/Understanding_crash_reports>`__
--  `A guide to searching crash
-   reports </en-US/docs/Mozilla/Projects/Crash_reporting/Searching_crash_reports>`__
+-  :ref:`Understanding crash reports`
+-  :ref:`A guide to searching crash reports`
 -  `crash-stats <https://crash-stats.mozilla.com/>`__
 -  `Crash pings (Telemetry) and crash reports (Socorro/Crash
    Stats) <https://bluesock.org/~willkg/blog/mozilla/crash_pings_crash_reports.html>`__
--  `Building Firefox with Debug
-   Symbols </en-US/docs/Building_Firefox_with_Debug_Symbols>`__
--  `Environment variables affecting crash
-   reporting <https://firefox-source-docs.mozilla.org/toolkit/crashreporter/crashreporter/index.html#environment-variables-affecting-crash-reporting>`__
--  `Uploading Symbols to Mozilla's Symbol
-   Server </en-US/docs/Uploading_symbols_to_Mozillas_symbol_server>`__
--  In-code documentation
-
-   -  `Crash
-      reporter <https://firefox-source-docs.mozilla.org/toolkit/crashreporter/crashreporter/index.html>`__
-   -  `Crash
-      manager <https://firefox-source-docs.mozilla.org/toolkit/components/crashes/crash-manager/index.html>`__
-   -  `Crash
-      ping <https://firefox-source-docs.mozilla.org/toolkit/components/telemetry/data/crash-ping.html>`__
+-  :ref:`Building with Debug Symbols`
+-  :ref:`Environment variables affecting crash reporting <Crash Reporter#Environment variables affecting crash reporting>`
+-  :ref:`Uploading symbols to Mozilla's symbol server`
+-  :ref:`Crash reporter`
+-  :ref:`Crash manager`
+-  :ref:`Crash ping`

docs/crash-reporting/searching_crash_reports.rst

@@ -9,7 +9,7 @@ A guide to searching crash reports
 
 The Mozilla `crash-stats <https://crash-stats.mozilla.com/>`__ site
 provides facilities for investigating large numbers of Firefox `crash
-reports <Understanding crash reports>`__ . This guide to
+reports <Understanding crash reports>`__. This guide to
 searching through crash reports may help you locate the crash reports
 that will help you find and fix the Firefox bug you're working on.
 
@@ -38,7 +38,7 @@ by clicking on the "Super Search" link near the toolbar at the top right
 of any page in crash-stats. This brings up a search form like the one in
 the following screenshot.
 
-|Results of a default search in crash-stats|
+|Search in crash-stats|
 
 Fields are provided for four common search criteria: product, version,
 platform, and process type. The product field is pre-populated with
@@ -246,7 +246,7 @@ documentation <https://crash-stats.mozilla.com/documentation/supersearch/>`__
 for full details; note that it uses the term "aggregation" for
 grouping/faceting.
 
-.. |Results of a default search in crash-stats| image:: img/super-search-form.png
+.. |Search in crash-stats| image:: img/super-search-form.png
 .. |Results of a default search in crash-stats| image:: img/default-search-results.png
 .. |Results of a default search in crash-stats (crash reports tab)| image:: img/default-search-results2.png
 .. |crash-stats Super Search form with additional criteria| image:: img/super-search-form2.png

docs/setup/contributing_code.rst

@@ -74,12 +74,10 @@ 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 `reviewer
-   checklist <https://developer.mozilla.org/docs/Developer_Guide/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
-   `Mach <https://developer.mozilla.org/docs/Mozilla/Developer_guide/mach>`_, its linting,
+-  Utilize our build tool :ref:`mach`, its linting,
    static analysis, and other code checking features
 
 Getting your code reviewed
@@ -199,4 +197,3 @@ form:
 -  `Mozilla platform development
    cheatsheet <https://web.archive.org/web/20160813112326/http://www.codefirefox.com:80/cheatsheet>`_
    (archive.org)
-

docs/setup/mach.rst

@@ -44,9 +44,8 @@ Try building the tree:
 
    $ ./mach build
 
-If you get error messages, make sure that you have all of the `build
-requisites </en-US/docs/Developer_Guide/Build_Instructions#Build_prerequisites>`__
-for your system.
+If you get error messages, make sure that you have all of the :ref:`build
+requisites <Getting Set Up To Work On The Firefox Codebase>` for your system.
 
 If it works, you can look at compiler warnings:
 
@@ -82,7 +81,7 @@ You run mach from the source directory, so you should be able to use
 your shell's tab completion to tab-complete paths to tests. Mach figures
 out how to execute the tests for you!
 
-Check out the linting and analysis tools:
+Check out the :ref:`linting` and :ref:`Static analysis` tools:
 
 .. code-block:: shell
 
@@ -207,7 +206,7 @@ client.mk:
    warnings are currently detected. Do not rely on mach as a substitute
    for raw build output.
 -  mach will invoke make in silent mode. This suppresses excessive
-   (often unncessary) output.
+   (often unnecessary) output.
 
 
 Is mach a build system?

docs/setup/macos_build.rst

@@ -328,8 +328,7 @@ couple hundred megabytes of data over the internet.
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 In your checked out source tree create a new file, ``mozconfig``, which
-will contain your build options. For more on this file, see `Configuring
-Build Options <https://developer.mozilla.org/en/Configuring_Build_Options>`_.
+will contain your build options. For more on this file, see :ref:`Configuring Build Options`.
 
 To get started quickly, create the file with the following contents:
 
@@ -407,7 +406,7 @@ Software requirements
 
 These options are specific to Mozilla builds for macOS. For a more
 general overview of build options and the ``mozconfig`` file, see
-`Configuring Build Options <https://developer.mozilla.org/en/Configuring_Build_Options>`_. For
+:ref:`Configuring Build Options`. For
 specific information on configuring to build a universal binary, see
 `Mac OS X Universal Binaries <https://developer.mozilla.org/en/Mac_OS_X_Universal_Binaries>`_.
 
@@ -444,8 +443,8 @@ are intended to be added to your ``mozconfig`` file.
 
        ac_add_options --with-macos-sdk=/path/to/SDK
 
-   Official trunk builds use ``/Developer/SDKs/MacOSX10.11.sdk``. Check
-   ```build/macosx/universal/mozconfig.common`` <https://dxr.mozilla.org/mozilla-central/source/build/macosx/cross-mozconfig.common#23>`_
+   Official trunk builds use `/Developer/SDKs/MacOSX10.11.sdk`. Check
+   `build/macosx/universal/mozconfig.common <https://searchfox.org/mozilla-central/source/build/macosx/cross-mozconfig.common>`__
    for the SDK version used for official builds of any particular source
    release.
 
@@ -484,4 +483,3 @@ Troubleshooting
    configuration file you're using for your chosen shell. Removing all
    modifications and then re-adding them one-by-one can narrow down
    problems.
-

moz.build

@@ -200,4 +200,6 @@ SPHINX_TREES['bug-mgmt'] = 'docs/bug-mgmt'
 
 SPHINX_TREES['setup'] = 'docs/setup'
 
+SPHINX_TREES['crash-reporting'] = 'docs/crash-reporting'
+
 include('build/templates.mozbuild')

taskcluster/docs/mach.rst

@@ -1,5 +1,5 @@
-Mach commands
-=============
+Taskcluster Mach commands
+=========================
 
 A number of mach subcommands are available aside from ``mach taskgraph
 decision`` to make this complex system more accessible to those trying to

toolkit/components/telemetry/docs/data/crash-ping.rst

@@ -1,6 +1,5 @@
-
-"crash" ping
-============
+Crash ping
+==========
 
 This ping is captured after the main Firefox process crashes or after a child process
 process crashes, whether or not the crash report is submitted to
@@ -14,7 +13,11 @@ successfully. The crash reporter client sends crash pings only for main process
 crashes whether or not the user also reports the crash. The crash reporter
 client will not send the crash ping if telemetry has been disabled in Firefox.
 
-The environment block that is sent with this ping varies: if Firefox was running long enough to record the environment block before the crash, then the environment at the time of the crash will be recorded and ``hasCrashEnvironment`` will be true. If Firefox crashed before the environment was recorded, ``hasCrashEnvironment`` will be false and the recorded environment will be the environment at time of submission.
+The environment block that is sent with this ping varies: if Firefox was running
+long enough to record the environment block before the crash, then the environment
+at the time of the crash will be recorded and ``hasCrashEnvironment`` will be true.
+If Firefox crashed before the environment was recorded, ``hasCrashEnvironment`` will
+be false and the recorded environment will be the environment at time of submission.
 
 The client ID is submitted with this ping.
 

toolkit/docs/index.rst

@@ -8,6 +8,7 @@ This is the nascent documentation of the Toolkit code that is shared across Fire
    :maxdepth: 1
 
    mozapps/extensions/addon-manager/index
+   crash-reporting/index
    components/crashes/crash-manager/index
    crashreporter/crashreporter/index
    components/featuregates/featuregates/index