fix: setup and use intersphinx mappings

We have the intersphinx extension enabled, but never set up the external
targets. This will allow us to more easily link to our other
documentation pages.

conf.py

@@ -4,16 +4,6 @@
 # list see the documentation:
 # https://www.sphinx-doc.org/en/master/usage/configuration.html
 
-# -- Path setup --------------------------------------------------------------
-
-# If extensions (or modules to document with autodoc) are in another directory,
-# add these directories to sys.path here. If the directory is relative to the
-# documentation root, use os.path.abspath to make it absolute, like shown here.
-#
-
-# import sys
-# sys.path.insert(0, os.path.abspath('.'))
-
 # -- Project information -----------------------------------------------------
 
 project = "RelEng"
@@ -50,6 +40,18 @@ templates_path = ["_templates"]
 # This pattern also affects html_static_path and html_extra_path.
 exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
 
+# Intersphinx allows linking to external Sphinx based documentation using the
+# standard roles and directives.
+intersphinx_mapping = {
+    "balrog": ("https://mozilla-balrog.readthedocs.io/en/latest", None),
+    "firefox": ("https://firefox-source-docs.mozilla.org", None),
+    "scriptworker": ("https://scriptworker.readthedocs.io/en/latest", None),
+    "scriptworker-scripts": (
+        "https://scriptworker-scripts.readthedocs.io/en/latest",
+        None,
+    ),
+    "taskgraph": ("https://taskcluster-taskgraph.readthedocs.io/en/latest", None),
+}
 
 # -- Options for HTML output -------------------------------------------------
 

explanations/balrog/index.rst

@@ -1,7 +1,7 @@
 Balrog Articles and Documentation
 =================================
 
-The main Balrog documentation can be found at https://mozilla-balrog.readthedocs.io/en/latest/.
+The main Balrog documentation can be found :external+balrog:doc:`here <index>`.
 
 Contents:
 

explanations/best-practices/bug-triage.rst

@@ -12,7 +12,7 @@ Goals of Bug Triage
 4. Identify 'low-hanging-fruits' with quick resolutions.
 5. Ensure bugs are considered triaged according to the Firefox triage process.
 
-This process is influenced by the `Firefox triage process <https://firefox-source-docs.mozilla.org/bug-mgmt/policies/triage-bugzilla.html>`_. However, we've adapted the definitions of bug severity to suit our needs.
+This process is influenced by the :external:doc:`Firefox triage process <bug-mgmt/policies/triage-bugzilla>`. However, we've adapted the definitions of bug severity to suit our needs.
 
 Bug Fields
 ----------

explanations/l10n.rst

@@ -20,7 +20,7 @@ So we extract all the strings from mozilla-central and we're done, yes? No.
 
 For Firefox Desktop, we follow the train model, so on merge day beta goes to release, and central goes to beta. Each of these repos can have different sets of strings: we have a set of strings, ideally frozen, on beta; but on central developers can change or land new strings for the next version of Firefox.
 
-Enter cross-channel (see the `cross-channel docs <https://firefox-source-docs.mozilla.org/l10n/crosschannel/index.html>`_). Cross-channel clones each of the active train repos for Firefox desktop and Thunderbird, extracts the strings, and combines them into a single set of strings for localizers to translate. (We include esr and release so we don't drop strings that are still in use.)
+Enter cross-channel (see the :external+firefox:doc:`cross-channel docs <l10n/crosschannel/index>`). Cross-channel clones each of the active train repos for Firefox desktop and Thunderbird, extracts the strings, and combines them into a single set of strings for localizers to translate. (We include esr and release so we don't drop strings that are still in use.)
 
 For Android, it's similar: we use the `android-l10n-tooling repository <https://github.com/mozilla-l10n/android-l10n-tooling/>`_ and its associated pulse-driven hooks to extract strings every time that code lands in our mobile repos.
 

explanations/taskcluster/how_tasks_are_triggered.rst

@@ -7,7 +7,7 @@ How are tasks triggered in Taskcluster?
 
 - You can create arbitrary tasks through, e.g. `the create task API/UI <https://firefox-ci-tc.services.mozilla.com/tasks/create>`__.
 - Or you can encode one or more tasks in `.taskcluster.yml <https://github.com/mozilla-releng/scriptworker/blob/8d35c98f58f0fb54367da854560721beb53f8f18/.taskcluster.yml>`__
-- If you pass a certain threshold of complexity, you probably want your ``.taskcluster.yml`` to schedule a decision task, which will create a task graph via `taskcluster-taskgraph <https://taskcluster-taskgraph.readthedocs.io/en/latest/>`__.
+- If you pass a certain threshold of complexity, you probably want your ``.taskcluster.yml`` to schedule a decision task, which will create a task graph via :external+taskgraph:doc:`Taskgraph <index>`.
 
 ... But what generates the task(s) in ``.taskcluster.yml``?
 

how-to/create/new-scriptworker-script.rst

@@ -6,7 +6,7 @@ This procedure is based on the experience of `adding the pushmsixscript to scrip
 * Write your new script and `add it to scriptworker-scripts <https://github.com/mozilla-releng/scriptworker-scripts/>`__.
 
  - You may want to clone-and-modify `an existing script <https://github.com/mozilla-releng/scriptworker-scripts/tree/master/pushmsixscript>`__.
- - Consult the `documentation <https://scriptworker-scripts.readthedocs.io>`__.
+ - Consult the :external+scriptworker-scripts:doc:`documentation <index>`.
  - Write unit tests for your script; you can run them locally with tox.
 
 * Add clients to ci-configuration repo
@@ -31,7 +31,7 @@ This procedure is based on the experience of `adding the pushmsixscript to scrip
 
 * Add entries to k8s-autoscale like `this <https://github.com/mozilla-releng/k8s-autoscale/pull/123>`__.
 
- - The `docs <https://scriptworker-scripts.readthedocs.io/en/latest/scriptworkers-autoscaling.html>`__ may be helpful.
+ - The :external:doc:`docs <scriptworkers-autoscaling>` may be helpful.
  - Merging will automatically trigger a dev deploy.
  - Be sure to deploy k8s-autoscale to production as well.
 

how-to/release/addons/openh264.rst

@@ -58,8 +58,7 @@ Create a new rule to test the release on the nightlytest channel:
     - on the Create Rule page, set Product = "OpenH264", Channel = "nightlytest" (or as needed), Mapping = the release you just created, Background Rate = 100 (or as needed), and set the Priority as needed, typically the lowest priority for the default rule.
     - on the Create Rule page, click "Create Rule" button in the lower right to create the rule.
 
-See https://mozilla-balrog.readthedocs.io/en/latest/database.html for
-general guidance on rule matching.
+See :external+balrog:doc:`this page <database>` for general guidance on rule matching.
 
 OpenH264 updates are generally sent to all channels, though we can restrict by update channel (e.g. ``esr*`` to only target esr users or nightlytest, the internal testing channel). This means users are given a new OpenH264 plugin based on their Firefox version. For instance: if we provide a new OpenH264 to 98.0 at the time 98.0b15 ships, then users with 98.0b1-b14 will also get this version. Make sure with the media team these betas are compatible! In the case it's not, please remember Firefox doesn't send which beta it's on to Balrog. You have to filter out based on the version **and** the buildID (the buildID alone doesn't work if a 97 dot release happens afterwards).
 

how-to/release/addons/widevine.rst

@@ -178,8 +178,7 @@ To implement this (assuming an existing default Widevine rule with priority 420)
     - when requested to add esr, create a new rule for esr* with priority 425
     - when requested to make the new CDM the default, update the default rule's release, then delete the other rules (nightlytest, nightly, beta, esr*).
 
-See https://mozilla-balrog.readthedocs.io/en/latest/database.html for
-general guidance on rule matching.
+See :external+balrog:doc:`this page <database>` for general guidance on rule matching.
 
 Unlike Firefox updates, Widevine ones all happen in the same channel
 (except for the nightlytest, the internal testing channel). This means

how-to/release/firefox/index.rst

@@ -144,8 +144,8 @@ Taskcluster
 Firefox is released via the same tooling that's used to build and test Firefox. We use our Mozilla in-house continuous
 integration (CI) platform `Taskcluster <https://docs.taskcluster.net/docs>`_ to drive the tasks and workers. The main
 service in this platform is the Taskcluster Queue. The queue takes requests of tasks and coordinates with a pool of
-workers to actually conduct the task work. The various scheduling and dependency logic is defined in `taskgraph
-<https://firefox-source-docs.mozilla.org/taskcluster/taskgraph.html>`_. The workers are trusted, locked down, and owned
+workers to actually conduct the task work. The various scheduling and dependency logic is defined in :external+firefox:doc:`Taskgraph
+<taskcluster/taskgraph>`. The workers are trusted, locked down, and owned
 by Release Engineering. They are `scriptworker <https://github.com/mozilla-releng/scriptworker>`_ based and the various
 implementations live `here <https://github.com/mozilla-releng/scriptworker-scripts>`_
 
@@ -158,8 +158,8 @@ We use signing scriptworkers that interface with Mozilla's `autograph service
 Providing Updates
 ^^^^^^^^^^^^^^^^^
 
-We use balrog scriptworkers that interface with Mozilla's `updater service, Balrog
-<https://mozilla-balrog.readthedocs.io/en/latest/>`_ 
+We use balrog scriptworkers that interface with Mozilla's :external+balrog:doc:`updater service, Balrog
+<index>`.
 
 Shipit
 ^^^^^^

how-to/releaseduty/desktop/staging-release.rst

@@ -19,8 +19,8 @@ How-To
 
 In order to prepare a smooth ``b1`` and ``RC``, staging releases should
 be run weekly or at least one week before RC week. In order for this to
-happen, we're using `staging releases submitted to
-try <https://firefox-source-docs.mozilla.org/tools/try/selectors/release.html>`__.
+happen, we're using :external+firefox:doc:`staging releases submitted to
+try <tools/try/selectors/release>`.
 
 **For central to beta migration**
 
@@ -70,10 +70,12 @@ Outside of mergeduty, during development cycles, we often need to work around a
 that entails changing the in-tree code or the ``*script`` itself. While
 triggering staging releases is a valid solution, it is often an
 expensive one as it generates an entire graph. In order to be more
-efficient, one can use the `scriptworker selector`_ which aims to run a
-selection of scriptworker tasks against builds from a recent release. There are a number of
-preset groups of tasks to run. The list is configured `here`_ and it get be extended for
-other tasks/products. To get the list of task sets, along with the list of tasks they will run:
+efficient, one can use the :external+firefox:doc:`scriptworker selector
+<tools/try/selectors/scriptworker>` which aims to run a selection of
+scriptworker tasks against builds from a recent release. There are a number of
+preset groups of tasks to run. The list is configured `here`_ and it get be
+extended for other tasks/products. To get the list of task sets, along with the
+list of tasks they will run:
 
 ::
 
@@ -96,7 +98,7 @@ for dev.
 
 But the latter is not present in-tree by default so it needs to be
 amended. More information on this can be found in the
-`scriptworker-scripts documentation`_. One can either manually change
+:external:doc:`scriptworker-scripts documentation <scriptworkers-dev>`. One can either manually change
 the intree kind's config to that specific worker-type, or can simply pass an
 argument to aforementioned command to make the replacement,
 e.g. ``mach try scriptworker TASK-TYPE --release-type beta --worker-suffix <alias>=<suffix>``,
@@ -109,9 +111,7 @@ release, but on the DEV worker-type:
 
    mach try scriptworker beetmover-candidates --release-type beta --worker-suffix beetmover=-dev
 
-.. _scriptworker selector: https://firefox-source-docs.mozilla.org/tools/try/selectors/scriptworker.html?highlight=scriptworker
 .. _here: https://hg.mozilla.org/mozilla-central/file/tip/tools/tryselect/selectors/scriptworker.py#l18
-.. _scriptworker-scripts documentation: https://scriptworker-scripts.readthedocs.io/en/latest/scriptworkers-dev.html
 .. _file: https://hg.mozilla.org/mozilla-central/file/tip/taskcluster/ci/config.yml#l437
 
 

how-to/taskcluster/index.rst

@@ -6,17 +6,13 @@ Administer Firefox-CI
 These external docs are relevant to Mozilla's Firefox-CI Taskcluster instance:
 
 - `Taskcluster docs`_
-- `Taskgraph docs`_
-- `Gecko in-tree taskcluster docs`_
-- `Scriptworker docs`_
-- `Scriptworker-scripts docs`_
+- :external+taskgraph:doc:`Taskgraph docs <index>`
+- :external+firefox:doc:`Gecko in-tree taskcluster docs <taskcluster/index>`
+- :external+scriptworker:doc:`Scriptworker docs <index>`
+- :external+scriptworker-scripts:doc:`Scriptworker-scripts docs <index>`
 - `Rotate CoT keys`_
 
 .. _Taskcluster docs: https://firefox-ci-tc.services.mozilla.com/docs
-.. _Taskgraph docs: https://taskcluster-taskgraph.readthedocs.io/en/latest/
-.. _Gecko in-tree taskcluster docs: https://firefox-source-docs.mozilla.org/taskcluster/taskcluster/index.html
-.. _Scriptworker docs: https://scriptworker.readthedocs.io/en/latest/
-.. _Scriptworker-scripts docs: https://scriptworker-scripts.readthedocs.io/en/latest/
 .. _Rotate CoT keys: https://mana.mozilla.org/wiki/display/RelEng/Chain+of+Trust+key+rotation?flashId=459232040
 
 .. toctree::

how-to/taskcluster/testing_relpro.rst

@@ -3,8 +3,7 @@ Testing and Customizing Release Promotion actions
 
 Actions in Taskgraph allow for adding, cancelling,
 retriggering/rerunning tasks in/to the graph. The action docs are
-currently
-`here <https://firefox-source-docs.mozilla.org/taskcluster/actions.html?highlight=action>`__.
+currently :external+taskgraph:doc:`here <howto/create-actions>`.
 
 We can test any available action with
 ``[./mach] taskgraph test-action-callback``, which takes input (schemas
@@ -196,7 +195,7 @@ Advanced relpro usage
 
 These two options allow for force-rebuilding certain tasks.
 
-``rebuild_kinds`` refers to a task `kind <https://firefox-source-docs.mozilla.org/taskcluster/kinds.html?highlight=kind>`__ that we want to make sure we rebuild. We use this in the `promote_firefox_partner_repack <https://hg.mozilla.org/mozilla-central/file/32a3cf57dd4396e123ebbba2f894e540528d0781/taskcluster/ci/config.yml#l220>`__ release promotion flavor; by listing the various ``release-partner-repack*`` kinds as ``rebuild_kinds``, we can:
+``rebuild_kinds`` refers to a task :external+firefox:doc:`kind <taskcluster/kinds>` that we want to make sure we rebuild. We use this in the `promote_firefox_partner_repack <https://hg.mozilla.org/mozilla-central/file/32a3cf57dd4396e123ebbba2f894e540528d0781/taskcluster/ci/config.yml#l220>`__ release promotion flavor; by listing the various ``release-partner-repack*`` kinds as ``rebuild_kinds``, we can:
 
 - use the exact same input for a given ``promote`` graph, adding the previous ``promote`` graph to the ``previous_graph_ids`` so we optimize away all the tasks in our new graph with the ``existing_tasks`` in the previous promote graph,
 - except we add the ``rebuild_kinds``, which means we end up just rebuilding the tasks with those kinds.