diff --git a/docs/config.yml b/docs/config.yml
index 36d83d0e840e..c68a1c0411e1 100644
--- a/docs/config.yml
+++ b/docs/config.yml
@@ -111,4 +111,4 @@ redirects:
 fatal warnings:
     - "WARNING: '([^']*)' reference target not found:((?!.rst).)*$"
 
-max_num_warnings: 6300
+max_num_warnings: 6220
diff --git a/python/mach/mach/decorators.py b/python/mach/mach/decorators.py
index 4ad0e2c19fff..fe4443e168e9 100644
--- a/python/mach/mach/decorators.py
+++ b/python/mach/mach/decorators.py
@@ -177,6 +177,8 @@ class Command(object):
 
     For example:
 
+    .. code-block:: python
+
         @Command('foo', category='misc', description='Run the foo action')
         def foo(self, command_context):
             pass
@@ -255,6 +257,8 @@ class CommandArgument(object):
 
     For example:
 
+    .. code-block:: python
+
         @Command('foo', help='Run the foo action')
         @CommandArgument('-b', '--bar', action='store_true', default=False,
             help='Enable bar mode.')
@@ -290,6 +294,8 @@ class CommandArgumentGroup(object):
 
     For example:
 
+    .. code-block: python
+
         @Command('foo', helps='Run the foo action')
         @CommandArgumentGroup('group1')
         @CommandArgument('-b', '--bar', group='group1', action='store_true',
diff --git a/python/mach/mach/main.py b/python/mach/mach/main.py
index 80bda5ca056b..9ab880341d83 100644
--- a/python/mach/mach/main.py
+++ b/python/mach/mach/main.py
@@ -36,8 +36,8 @@ from .telemetry import create_telemetry_from_environment, report_invocation_metr
 from .util import UserError, setenv
 
 SUGGEST_MACH_BUSTED_TEMPLATE = r"""
-You can invoke |./mach busted| to check if this issue is already on file. If it
-isn't, please use |./mach busted file %s| to report it. If |./mach busted| is
+You can invoke ``./mach busted`` to check if this issue is already on file. If it
+isn't, please use ``./mach busted file %s`` to report it. If ``./mach busted`` is
 misbehaving, you can also inspect the dependencies of bug 1543241.
 """.lstrip()
 
@@ -82,13 +82,13 @@ a bug in the called code itself or in the way that mach is calling it.
 NO_COMMAND_ERROR = r"""
 It looks like you tried to run mach without a command.
 
-Run |mach help| to show a list of commands.
+Run ``mach help`` to show a list of commands.
 """.lstrip()
 
 UNKNOWN_COMMAND_ERROR = r"""
 It looks like you are trying to %s an unknown mach command: %s
 %s
-Run |mach help| to show a list of commands.
+Run ``mach help`` to show a list of commands.
 """.lstrip()
 
 SUGGESTED_COMMANDS_MESSAGE = r"""
@@ -195,7 +195,7 @@ class Mach(object):
 
         populate_context_handler -- If defined, it must be a callable. The
             callable signature is the following:
-                populate_context_handler(key=None)
+            populate_context_handler(key=None)
             It acts as a fallback getter for the mach.base.CommandContext
             instance.
             This allows to augment the context instance with arbitrary data
diff --git a/python/mach/mach/mixin/logging.py b/python/mach/mach/mixin/logging.py
index f40bd64356b8..4ba6955a2d6e 100644
--- a/python/mach/mach/mixin/logging.py
+++ b/python/mach/mach/mixin/logging.py
@@ -42,10 +42,11 @@ class LoggingMixin(object):
         performed by calling format() on this string, feeding into it the dict
         of attributes constituting the event.
 
-        Example Usage
-        -------------
+        Example Usage:
 
-        self.log(logging.DEBUG, 'login', {'username': 'johndoe'},
-            'User login: {username}')
+        .. code-block:: python
+
+            self.log(logging.DEBUG, 'login', {'username': 'johndoe'},
+                'User login: {username}')
         """
         self._logger.log(level, format_str, extra={"action": action, "params": params})
diff --git a/python/mach/mach/site.py b/python/mach/mach/site.py
index d6bccc043551..58c1eac3fafe 100644
--- a/python/mach/mach/site.py
+++ b/python/mach/mach/site.py
@@ -444,13 +444,16 @@ class CommandSiteManager:
     used standalone to invoke a script).
 
     A few notes:
-    * The command environment always inherits Mach's import scope. This is because
-      "unloading" packages in Python is error-prone, so in-process activations will always
-      carry Mach's dependencies along with it. Accordingly, compatibility between each
-      command environment and the Mach environment must be maintained
+
+    * The command environment always inherits Mach's import scope. This is
+      because "unloading" packages in Python is error-prone, so in-process activations
+      will always carry Mach's dependencies along with it. Accordingly, compatibility
+      between each command environment and the Mach environment must be maintained
+
     * Unlike the Mach environment, command environments *always* have an associated
       physical virtualenv on-disk. This is because some commands invoke child Python
       processes, and that child process should have the same import scope.
+
     """
 
     def __init__(
diff --git a/python/mozbuild/mozbuild/action/buildlist.py b/python/mozbuild/mozbuild/action/buildlist.py
index 6372b4c14b10..ab32ad92cc87 100644
--- a/python/mozbuild/mozbuild/action/buildlist.py
+++ b/python/mozbuild/mozbuild/action/buildlist.py
@@ -16,8 +16,8 @@ from mozbuild.util import ensureParentDir, lock_file
 
 
 def addEntriesToListFile(listFile, entries):
-    """Given a file |listFile| containing one entry per line,
-    add each entry in |entries| to the file, unless it is already
+    """Given a file ``listFile`` containing one entry per line,
+    add each entry in ``entries`` to the file, unless it is already
     present."""
     ensureParentDir(listFile)
     lock = lock_file(listFile + ".lck")
diff --git a/python/mozbuild/mozbuild/action/process_define_files.py b/python/mozbuild/mozbuild/action/process_define_files.py
index 6b00cd36cd4d..d775b52b57b6 100644
--- a/python/mozbuild/mozbuild/action/process_define_files.py
+++ b/python/mozbuild/mozbuild/action/process_define_files.py
@@ -15,13 +15,14 @@ from mozbuild.backend.configenvironment import PartialConfigEnvironment
 
 def process_define_file(output, input):
     """Creates the given config header. A config header is generated by
-    taking the corresponding source file and replacing some #define/#undef
+    taking the corresponding source file and replacing some *#define/#undef*
     occurences:
-        "#undef NAME" is turned into "#define NAME VALUE"
-        "#define NAME" is unchanged
-        "#define NAME ORIGINAL_VALUE" is turned into "#define NAME VALUE"
-        "#undef UNKNOWN_NAME" is turned into "/* #undef UNKNOWN_NAME */"
-        Whitespaces are preserved.
+
+      - "#undef NAME" is turned into "#define NAME VALUE"
+      - "#define NAME" is unchanged
+      - "#define NAME ORIGINAL_VALUE" is turned into "#define NAME VALUE"
+      - "#undef UNKNOWN_NAME" is turned into "/* #undef UNKNOWN_NAME */"
+      -  Whitespaces are preserved.
 
     As a special rule, "#undef ALLDEFINES" is turned into "#define NAME
     VALUE" for all the defined variables.
diff --git a/python/mozbuild/mozbuild/artifact_cache.py b/python/mozbuild/mozbuild/artifact_cache.py
index 2de721986cfd..572953e1f718 100644
--- a/python/mozbuild/mozbuild/artifact_cache.py
+++ b/python/mozbuild/mozbuild/artifact_cache.py
@@ -61,11 +61,14 @@ class ArtifactPersistLimit(dlmanager.PersistLimit):
     After a download finishes, the newly downloaded file is registered, and the
     oldest files registered to the PersistLimit instance are removed depending
     on the size and file limits it's configured for.
+
     This is all good, but there are a few tweaks we want here:
-    - We have pickle files in the cache directory that we don't want purged.
-    - Files that were just downloaded in the same session shouldn't be purged.
-      (if for some reason we end up downloading more than the default max size,
-       we don't want the files to be purged)
+
+      - We have pickle files in the cache directory that we don't want purged.
+      - Files that were just downloaded in the same session shouldn't be
+        purged. (if for some reason we end up downloading more than the default
+        max size, we don't want the files to be purged)
+
     To achieve this, this subclass of PersistLimit inhibits the register_file
     method for pickle files and tracks what files were downloaded in the same
     session to avoid removing them.
diff --git a/python/mozbuild/mozbuild/artifact_commands.py b/python/mozbuild/mozbuild/artifact_commands.py
index a481269da18d..fb0bb13a29c0 100644
--- a/python/mozbuild/mozbuild/artifact_commands.py
+++ b/python/mozbuild/mozbuild/artifact_commands.py
@@ -64,10 +64,10 @@ class ArtifactSubCommand(SubCommand):
 def artifact(command_context):
     """Download, cache, and install pre-built binary artifacts to build Firefox.
 
-    Use |mach build| as normal to freshen your installed binary libraries:
+    Use ``mach build`` as normal to freshen your installed binary libraries:
     artifact builds automatically download, cache, and install binary
     artifacts from Mozilla automation, replacing whatever may be in your
-    object directory.  Use |mach artifact last| to see what binary artifacts
+    object directory.  Use ``mach artifact last`` to see what binary artifacts
     were last used.
 
     Never build libxul again!
diff --git a/python/mozbuild/mozbuild/artifacts.py b/python/mozbuild/mozbuild/artifacts.py
index c06c7785bb4b..2ed96fb520f7 100644
--- a/python/mozbuild/mozbuild/artifacts.py
+++ b/python/mozbuild/mozbuild/artifacts.py
@@ -27,7 +27,7 @@ This module performs the following steps:
   so we don't have to mount DMG files frequently.
 
 This module requires certain modules be importable from the ambient Python
-environment.  |mach artifact| ensures these modules are available, but other
+environment.  ``mach artifact`` ensures these modules are available, but other
 consumers will need to arrange this themselves.
 """
 
diff --git a/python/mozbuild/mozbuild/backend/base.py b/python/mozbuild/mozbuild/backend/base.py
index 1d7b3bec1efd..ba81c330f538 100644
--- a/python/mozbuild/mozbuild/backend/base.py
+++ b/python/mozbuild/mozbuild/backend/base.py
@@ -255,7 +255,7 @@ class BuildBackend(LoggingMixin):
         status value of a subprocess, where 0 denotes success and any
         other value is an error code.
 
-        If an exception is raised, |mach build| will fail with a
+        If an exception is raised, ``mach build`` will fail with a
         non-zero exit code.
         """
         self._write_purgecaches(config)
diff --git a/python/mozbuild/mozbuild/backend/configenvironment.py b/python/mozbuild/mozbuild/backend/configenvironment.py
index 2f4f3baec9a3..eef1b62ee634 100644
--- a/python/mozbuild/mozbuild/backend/configenvironment.py
+++ b/python/mozbuild/mozbuild/backend/configenvironment.py
@@ -88,8 +88,7 @@ class ConfigEnvironment(object):
     Creating a ConfigEnvironment requires a few arguments:
       - topsrcdir and topobjdir are, respectively, the top source and
         the top object directory.
-      - defines is a dict filled from AC_DEFINE and AC_DEFINE_UNQUOTED in
-        autoconf.
+      - defines is a dict filled from AC_DEFINE and AC_DEFINE_UNQUOTED in autoconf.
       - substs is a dict filled from AC_SUBST in autoconf.
 
     ConfigEnvironment automatically defines one additional substs variable
@@ -97,15 +96,15 @@ class ConfigEnvironment(object):
       - ACDEFINES contains the defines in the form -DNAME=VALUE, for use on
         preprocessor command lines. The order in which defines were given
         when creating the ConfigEnvironment is preserved.
+
     and two other additional subst variables from all the other substs:
       - ALLSUBSTS contains the substs in the form NAME = VALUE, in sorted
-        order, for use in autoconf.mk. It includes ACDEFINES
+        order, for use in autoconf.mk. It includes ACDEFINES.
         Only substs with a VALUE are included, such that the resulting file
         doesn't change when new empty substs are added.
         This results in less invalidation of build dependencies in the case
         of autoconf.mk..
-      - ALLEMPTYSUBSTS contains the substs with an empty value, in the form
-        NAME =.
+      - ALLEMPTYSUBSTS contains the substs with an empty value, in the form NAME =.
 
     ConfigEnvironment expects a "top_srcdir" subst to be set with the top
     source directory, in msys format on windows. It is used to derive a
@@ -314,14 +313,16 @@ class PartialConfigEnvironment(object):
 
     The PartialConfigEnvironment automatically defines one additional subst variable
     from all the defines:
+
       - ACDEFINES contains the defines in the form -DNAME=VALUE, for use on
         preprocessor command lines. The order in which defines were given
         when creating the ConfigEnvironment is preserved.
 
     and one additional define from all the defines as a dictionary:
+
       - ALLDEFINES contains all of the global defines as a dictionary. This is
-      intended to be used instead of the defines structure from config.status so
-      that scripts can depend directly on its value.
+        intended to be used instead of the defines structure from config.status so
+        that scripts can depend directly on its value.
     """
 
     def __init__(self, topobjdir):
diff --git a/python/mozbuild/mozbuild/backend/recursivemake.py b/python/mozbuild/mozbuild/backend/recursivemake.py
index dc18946dbc4f..6b3b95242d68 100644
--- a/python/mozbuild/mozbuild/backend/recursivemake.py
+++ b/python/mozbuild/mozbuild/backend/recursivemake.py
@@ -251,6 +251,7 @@ class RecursiveMakeTraversal(object):
 
         filter is a function with the following signature:
             def filter(current, subdirs)
+
         where current is the directory being traversed, and subdirs the
         SubDirectories instance corresponding to it.
         The filter function returns a tuple (filtered_current, filtered_parallel,
diff --git a/python/mozbuild/mozbuild/faster_daemon.py b/python/mozbuild/mozbuild/faster_daemon.py
index 9988532a2e6f..d3d87f85b75a 100644
--- a/python/mozbuild/mozbuild/faster_daemon.py
+++ b/python/mozbuild/mozbuild/faster_daemon.py
@@ -3,8 +3,8 @@
 # file, You can obtain one at http://mozilla.org/MPL/2.0/.
 
 """
-Use pywatchman to watch source directories and perform partial |mach
-build faster| builds.
+Use pywatchman to watch source directories and perform partial
+``mach build faster`` builds.
 """
 
 import datetime
diff --git a/python/mozbuild/mozbuild/frontend/context.py b/python/mozbuild/mozbuild/frontend/context.py
index 0618249622df..39984f729f20 100644
--- a/python/mozbuild/mozbuild/frontend/context.py
+++ b/python/mozbuild/mozbuild/frontend/context.py
@@ -870,7 +870,7 @@ class Path(six.with_metaclass(PathMeta, ContextDerivedValue, six.text_type)):
         return self
 
     def join(self, *p):
-        """ContextDerived equivalent of mozpath.join(self, *p), returning a
+        """ContextDerived equivalent of `mozpath.join(self, *p)`, returning a
         new Path instance.
         """
         return Path(self.context, mozpath.join(self, *p))
@@ -1034,10 +1034,12 @@ def ContextDerivedTypedRecord(*fields):
     This API is extremely similar to the TypedNamedTuple API,
     except that properties may be mutated. This supports syntax like:
 
-    VARIABLE_NAME.property += [
-      'item1',
-      'item2',
-    ]
+    .. code-block:: python
+
+        VARIABLE_NAME.property += [
+          'item1',
+          'item2',
+        ]
     """
 
     class _TypedRecord(ContextDerivedValue):
diff --git a/python/mozbuild/mozbuild/frontend/reader.py b/python/mozbuild/mozbuild/frontend/reader.py
index edab024d0c80..545faef0b7fd 100644
--- a/python/mozbuild/mozbuild/frontend/reader.py
+++ b/python/mozbuild/mozbuild/frontend/reader.py
@@ -1066,7 +1066,7 @@ class BuildReader(object):
         This starts with a single mozbuild file, executes it, and descends into
         other referenced files per our traversal logic.
 
-        The traversal logic is to iterate over the *DIRS variables, treating
+        The traversal logic is to iterate over the ``*DIRS`` variables, treating
         each element as a relative directory path. For each encountered
         directory, we will open the moz.build file located in that
         directory in a new Sandbox and process it.
diff --git a/python/mozbuild/mozbuild/makeutil.py b/python/mozbuild/mozbuild/makeutil.py
index 96bda4f87fb9..76691c5fa10a 100644
--- a/python/mozbuild/mozbuild/makeutil.py
+++ b/python/mozbuild/mozbuild/makeutil.py
@@ -99,9 +99,7 @@ class _SimpleOrderedSet(object):
 class Rule(object):
     """Class handling simple rules in the form:
     target1 target2 ... : dep1 dep2 ...
-            command1
-            command2
-            ...
+    command1 command2 ...
     """
 
     def __init__(self, targets=()):
diff --git a/python/mozbuild/mozbuild/test/backend/test_recursivemake.py b/python/mozbuild/mozbuild/test/backend/test_recursivemake.py
index 2286a40cee9c..acbada060b1a 100644
--- a/python/mozbuild/mozbuild/test/backend/test_recursivemake.py
+++ b/python/mozbuild/mozbuild/test/backend/test_recursivemake.py
@@ -994,7 +994,7 @@ class TestRecursiveMakeBackend(BackendTester):
         self.assertEqual(lines, expected)
 
     def test_rust_programs(self):
-        """Test that {HOST_,}RUST_PROGRAMS are written to backend.mk correctly."""
+        """Test that `{HOST_,}RUST_PROGRAMS` are written to backend.mk correctly."""
         env = self._consume("rust-programs", RecursiveMakeBackend)
 
         backend_path = mozpath.join(env.topobjdir, "code/backend.mk")
diff --git a/python/mozbuild/mozbuild/util.py b/python/mozbuild/mozbuild/util.py
index 1f06e42c5932..d0c72a07d001 100644
--- a/python/mozbuild/mozbuild/util.py
+++ b/python/mozbuild/mozbuild/util.py
@@ -707,6 +707,9 @@ def StrictOrderingOnAppendListWithFlagsFactory(flags):
     the flag names, and values the type used for the value of that flag.
 
     Example:
+
+    .. code-block:: python
+
         FooList = StrictOrderingOnAppendListWithFlagsFactory({
             'foo': bool, 'bar': unicode
         })
diff --git a/python/mozbuild/mozbuild/vendor/rewrite_mozbuild.py b/python/mozbuild/mozbuild/vendor/rewrite_mozbuild.py
index cd051a919228..8163c05dc3e2 100644
--- a/python/mozbuild/mozbuild/vendor/rewrite_mozbuild.py
+++ b/python/mozbuild/mozbuild/vendor/rewrite_mozbuild.py
@@ -13,10 +13,11 @@ Problem:
     be able to effectively update a library automatically and send useful try runs in.
 
     So far, it has been difficult to do that.
+
     Why:
-        Some files need to go into UNIFIED_SOURCES vs SOURCES
-        Some files are os-specific, and need to go into per-OS conditionals
-        Some files are both UNIFIED_SOURCES/SOURCES sensitive and OS-specific.
+        - Some files need to go into UNIFIED_SOURCES vs SOURCES
+        - Some files are os-specific, and need to go into per-OS conditionals
+        - Some files are both UNIFIED_SOURCES/SOURCES sensitive and OS-specific.
 
 Proposal:
     Design an algorithm that maps a third party library file to a suspected moz.build location.
@@ -25,17 +26,17 @@ Proposal:
 
 Initial Algorithm
     Given a file, which includes the filename and the path from gecko root, we want to find the
-        correct moz.build file and location within that file.
+    correct moz.build file and location within that file.
     Take the path of the file, and iterate up the directory tree, looking for moz.build files as
     we go.
     Consider each of these moz.build files, starting with the one closest to the file.
     Within a moz.build file, identify the SOURCES or UNIFIED_SOURCES block(s) that contains a file
-        in the same directory path as the file to be added.
+    in the same directory path as the file to be added.
     If there is only one such block, use that one.
     If there are multiple blocks, look at the files within each block and note the longest length
-        of a common prefix (including partial filenames - if we just did full directories the
-        result would be the same as the prior step and we would not narrow the results down). Use
-        the block containing the longest prefix. (We call this 'guessing'.)
+    of a common prefix (including partial filenames - if we just did full directories the
+    result would be the same as the prior step and we would not narrow the results down). Use
+    the block containing the longest prefix. (We call this 'guessing'.)
 
 Result of the proposal:
     The initial implementation works on 1675 of 1977 elligible files.
@@ -46,8 +47,8 @@ Result of the proposal:
         - per-cpu-feature files, where only a single file is added under a conditional
         - When guessing, because of a len(...) > longest_so_far comparison, we would prefer the
           first block we found.
-          -  Changing this to prefer UNIFIED_SOURCES in the event of a tie
-             yielded 17 additional correct assignments (about a 1% improvement)
+          - Changing this to prefer UNIFIED_SOURCES in the event of a tie
+            yielded 17 additional correct assignments (about a 1% improvement)
         - As a result of the change immediately above, when guessing, because given equal
           prefixes, we would prefer a UNIFIED_SOURCES block over other blocks, even if the other
           blocks are longer
@@ -59,6 +60,7 @@ Result of the proposal:
         - Those specified in source assignments composed of generators (e.g. [f for f in '%.c'])
         - Those specified in source assignments to subscripted variables
           (e.g. SOURCES += foo['x86_files'])
+
     We needed to iterate up the directory and look at a different moz.build file _zero_ times.
         This indicates this code is probably not needed, and therefore we will remove it from the
         algorithm.
@@ -87,7 +89,7 @@ source-assignment
     We specifically look only for these two variable names to avoid identifying things
     such as CXX_FLAGS.
 
-    Sometimes; however, there is an intermediary variable, such as SOURCES += celt_filenames
+    Sometimes; however, there is an intermediary variable, such as `SOURCES += celt_filenames`
     In this situation we find the celt_filenames assignment, and treat it as a 'source-assignment'
 
 source-assignment-location
@@ -106,12 +108,12 @@ source-assignment-location
 
     For example:
 
-    When SOURCES += ['ffpvx.xpp'] appears as the first line of the file (or any other
-    unindented-location) its source-assignment-location will be "> SOURCES 1".
+    When `SOURCES += ['ffpvx.xpp']` appears as the first line of the file (or any other
+    unindented-location) its source-assignment-location will be `> SOURCES 1`.
 
-    When SOURCES += ['ffpvx.xpp'] appears inside a conditional such as
+    When `SOURCES += ['ffpvx.xpp']` appears inside a conditional such as
     `CONFIG['OS_TARGET'] == 'WINNT'` then its source-assignment-location will be
-    "> if CONFIG['OS_TARGET'] == 'WINNT' > SOURCES 1"
+    `> if CONFIG['OS_TARGET'] == 'WINNT' > SOURCES 1`
 
     When SOURCES += ['ffpvx.xpp'] appears as the second line of the file, and a different
     SOURCES += [] was the first line, then its source-assignment-location will be "> SOURCES 2".
@@ -146,9 +148,9 @@ normalized-filename
 
     Normalization gets more complicated when dealing with separate vendoring and moz.yaml
     directories. This is because a file can be considered normalized when it looks like
-       third_party/libdav1d/src/a.cpp
+    third_party/libdav1d/src/a.cpp
     _or_ when it looks like
-       media/libdav1d/../../third_party/libdav1d/src/a.cpp
+    media/libdav1d/../../third_party/libdav1d/src/a.cpp
     This is because in the moz.build file, it will be specified as
     `../../third_party/libdav1d/src/a.cpp` and we 'normalize' it by prepending the path to the
     moz.build file.
@@ -162,13 +164,13 @@ normalized-filename
     Whenever a filename is normalized, it should be specified as such in the variable name,
     either as a prefix (normalized_filename) or a suffix (target_filename_normalized)
 
-statistic_
+statistic
     Using some hacky stuff, we report statistics about how many times we hit certain branches of
     the code.
     e.g.
-        "How many times did we refine a guess based on prefix length"
-        "How many times did we refine a guess based on the number of files in the block"
-        "What is the histogram of guess candidates"
+      - "How many times did we refine a guess based on prefix length"
+      - "How many times did we refine a guess based on the number of files in the block"
+      - "What is the histogram of guess candidates"
 
     We do this to identify how frequently certain code paths were taken, allowing us to identify
     strange behavior and investigate outliers. This process lead to identifying bugs and small
@@ -524,11 +526,13 @@ def get_mozbuild_file_search_order(
     Returns an ordered list of normalized moz.build filenames to consider for a given filename
 
     normalized_filename: a source filename normalized to the gecko root
-    moz_yaml_dir: the path from gecko_root to the moz.yaml file (which is the root of the
-                  moz.build files)
-    moz_yaml_dir: the path to where the library's source files are
-    all_mozbuild_filenames_normalized: (optional) the list of all third-party moz.build files
 
+    moz_yaml_dir: the path from gecko_root to the moz.yaml file (which is the root of the
+    moz.build files)
+
+    moz_yaml_dir: the path to where the library's source files are
+
+    all_mozbuild_filenames_normalized: (optional) the list of all third-party moz.build files
     If all_mozbuild_filenames_normalized is not specified, we look in the filesystem.
 
     The list is built out of two distinct steps.
@@ -541,6 +545,9 @@ def get_mozbuild_file_search_order(
     directory.
 
     Example:
+
+    .. code-block:: python
+
         When moz_yaml directory != vendoring_directory:
             moz_yaml_dir = foo/bar/
             vendoring_dir = third_party/baz/
@@ -680,7 +687,7 @@ def guess_best_assignment(source_assignments, filename_normalized):
     assignment which contains a filename with the longest matching prefix.
 
     e.g: "foo/asm_neon.c" compared to ["foo/main.c", "foo/all_utility.c"], ["foo/asm_arm.c"]
-            -> ["foo/asm_arm.c"] (match of foo/asm_)
+            -> ["foo/asm_arm.c"] (match of `foo/asm_`)
     """
     length_of_longest_match = 0
     source_assignment_location_of_longest_match = None
@@ -722,9 +729,9 @@ def edit_moz_build_file_to_add_file(
     I had _really_ hoped to replace this whole damn thing with something that adds a
     node to the AST, dumps the AST out, and then runs black on the file but there are
     some issues:
-      - third party moz.build files (or maybe all moz.build files) aren't always run
-        through black
-      - dumping the ast out losing comments
+    - third party moz.build files (or maybe all moz.build files) aren't always run through black
+    - dumping the ast out losing comments
+
     """
 
     # Make sure that we only write in forward slashes
diff --git a/python/mozbuild/mozpack/errors.py b/python/mozbuild/mozpack/errors.py
index eeb8632fbb24..25c0e8549ca0 100644
--- a/python/mozbuild/mozpack/errors.py
+++ b/python/mozbuild/mozpack/errors.py
@@ -21,41 +21,54 @@ class ErrorCollector(object):
 
     Warnings, errors and fatal errors may be logged by calls to the following
     functions:
-        errors.warn(message)
-        errors.error(message)
-        errors.fatal(message)
+      - errors.warn(message)
+      - errors.error(message)
+      - errors.fatal(message)
 
     Warnings only send the message on the logging output, while errors and
     fatal errors send the message and throw an ErrorMessage exception. The
     exception, however, may be deferred. See further below.
 
     Errors may be ignored by calling:
-        errors.ignore_errors()
+      - errors.ignore_errors()
 
     After calling that function, only fatal errors throw an exception.
 
     The warnings, errors or fatal errors messages may be augmented with context
     information when a context is provided. Context is defined by a pair
     (filename, linenumber), and may be set with errors.context() used as a
+
     context manager:
+
+    .. code-block:: python
+
         with errors.context(filename, linenumber):
             errors.warn(message)
 
     Arbitrary nesting is supported, both for errors.context calls:
+
+    .. code-block:: python
+
         with errors.context(filename1, linenumber1):
             errors.warn(message)
             with errors.context(filename2, linenumber2):
                 errors.warn(message)
 
     as well as for function calls:
+
+    .. code-block:: python
+
         def func():
             errors.warn(message)
-        with errors.context(filename, linenumber):
-            func()
+            with errors.context(filename, linenumber):
+                func()
 
     Errors and fatal errors can have their exception thrown at a later time,
     allowing for several different errors to be reported at once before
     throwing. This is achieved with errors.accumulate() as a context manager:
+
+    .. code-block:: python
+
         with errors.accumulate():
             if test1:
                 errors.error(message1)
diff --git a/python/mozbuild/mozpack/executables.py b/python/mozbuild/mozpack/executables.py
index 96bcd40fae76..dd6849cabe3c 100644
--- a/python/mozbuild/mozpack/executables.py
+++ b/python/mozbuild/mozpack/executables.py
@@ -66,9 +66,8 @@ def is_executable(path):
     """
     Return whether a given file path points to an executable or a library,
     where an executable or library is identified by:
-        - the file extension on OS/2 and WINNT
-        - the file signature on OS/X and ELF systems (GNU/Linux, Android, BSD,
-          Solaris)
+    - the file extension on OS/2 and WINNT
+    - the file signature on OS/X and ELF systems (GNU/Linux, Android, BSD, Solaris)
 
     As this function is intended for use to choose between the ExecutableFile
     and File classes in FileFinder, and choosing ExecutableFile only matters
diff --git a/python/mozbuild/mozpack/files.py b/python/mozbuild/mozpack/files.py
index 7a996f65ecea..ba8c5d9f1366 100644
--- a/python/mozbuild/mozpack/files.py
+++ b/python/mozbuild/mozpack/files.py
@@ -68,12 +68,9 @@ def _open(path, mode="r"):
 class Dest(object):
     """
     Helper interface for BaseFile.copy. The interface works as follows:
-    - read() and write() can be used to sequentially read/write from the
-      underlying file.
-    - a call to read() after a write() will re-open the underlying file and
-      read from it.
-    - a call to write() after a read() will re-open the underlying file,
-      emptying it, and write to it.
+      - read() and write() can be used to sequentially read/write from the underlying file.
+      - a call to read() after a write() will re-open the underlying file and read from it.
+      - a call to write() after a read() will re-open the underlying file, emptying it, and write to it.
     """
 
     def __init__(self, path):
@@ -1115,8 +1112,8 @@ class ComposedFinder(BaseFinder):
     """
     Composes multiple File Finders in some sort of virtual file system.
 
-    A ComposedFinder is initialized from a dictionary associating paths to
-    *Finder instances.
+    A ComposedFinder is initialized from a dictionary associating paths
+    to `*Finder instances.`
 
     Note this could be optimized to be smarter than getting all the files
     in advance.
diff --git a/python/mozbuild/mozpack/mozjar.py b/python/mozbuild/mozpack/mozjar.py
index f9db5b9aca2a..c98412013723 100644
--- a/python/mozbuild/mozpack/mozjar.py
+++ b/python/mozbuild/mozpack/mozjar.py
@@ -39,19 +39,24 @@ class JarStruct(object):
     field names. In the latter case, the field is considered to be a string
     buffer with a length given in that field.
     For example,
+
+    .. code-block:: python
+
         STRUCT = [
             ('version', 'uint32'),
             ('filename_size', 'uint16'),
             ('filename', 'filename_size')
         ]
+
     describes a structure with a 'version' 32-bits unsigned integer field,
     followed by a 'filename_size' 16-bits unsigned integer field, followed by a
     filename_size-long string buffer 'filename'.
 
     Fields that are used as other fields size are not stored in objects. In the
     above example, an instance of such subclass would only have two attributes:
-        obj['version']
-        obj['filename']
+      - obj['version']
+      - obj['filename']
+
     filename_size would be obtained with len(obj['filename']).
 
     JarStruct subclasses instances can be either initialized from existing data
@@ -561,6 +566,7 @@ class JarWriter(object):
             - (...)
             - End of central directory, pointing at first central directory
               entry.
+
         The duplication of the End of central directory is to accomodate some
         Zip reading tools that want an end of central directory structure to
         follow the central directory entries.
diff --git a/python/mozbuild/mozpack/unify.py b/python/mozbuild/mozpack/unify.py
index 1bb9b8156b3f..3cc5c037676f 100644
--- a/python/mozbuild/mozpack/unify.py
+++ b/python/mozbuild/mozpack/unify.py
@@ -208,7 +208,7 @@ class UnifiedFinder(BaseFinder):
 class UnifiedBuildFinder(UnifiedFinder):
     """
     Specialized UnifiedFinder for Mozilla applications packaging. It allows
-    "*.manifest" files to differ in their order, and unifies "buildconfig.html"
+    ``*.manifest`` files to differ in their order, and unifies ``buildconfig.html``
     files by merging their content.
     """
 
diff --git a/python/mozlint/mozlint/result.py b/python/mozlint/mozlint/result.py
index 2e7b885fd509..01b04afee601 100644
--- a/python/mozlint/mozlint/result.py
+++ b/python/mozlint/mozlint/result.py
@@ -123,11 +123,14 @@ class Issue(object):
 
 
 class IssueEncoder(JSONEncoder):
-    """Class for encoding :class:`~result.Issue`s to json.
+    """Class for encoding :class:`~result.Issue` to json.
 
     Usage:
 
+    .. code-block:: python
+
         json.dumps(results, cls=IssueEncoder)
+
     """
 
     def default(self, o):
diff --git a/python/mozlint/mozlint/util/implementation.py b/python/mozlint/mozlint/util/implementation.py
index 4bf3c53a705e..9c72c0ea0f61 100644
--- a/python/mozlint/mozlint/util/implementation.py
+++ b/python/mozlint/mozlint/util/implementation.py
@@ -21,7 +21,7 @@ class LintProcess(ProcessHandlerMixin, ABC):
     def process_line(self, line):
         """Process a single line of output.
 
-        The implementation is responsible for creating one or more :class:`~mozlint.result.Issue`s
+        The implementation is responsible for creating one or more :class:`~mozlint.result.Issue`
         and storing them somewhere accessible.
 
         Args:
diff --git a/taskcluster/gecko_taskgraph/actions/registry.py b/taskcluster/gecko_taskgraph/actions/registry.py
index 23fa8b4853d9..0c99e68d2080 100644
--- a/taskcluster/gecko_taskgraph/actions/registry.py
+++ b/taskcluster/gecko_taskgraph/actions/registry.py
@@ -116,7 +116,7 @@ def register_callback_action(
         JSON schema specifying input accepted by the action.
         This is optional and can be left ``null`` if no input is taken.
     permission : string
-        This defaults to ``generic` and needs to be set for actions that need
+        This defaults to ``generic`` and needs to be set for actions that need
         additional permissions. It appears appears in ci-configuration and
         various role and hook
         names.
diff --git a/taskcluster/gecko_taskgraph/loader/multi_dep.py b/taskcluster/gecko_taskgraph/loader/multi_dep.py
index b7b3036760ed..04fda0441554 100644
--- a/taskcluster/gecko_taskgraph/loader/multi_dep.py
+++ b/taskcluster/gecko_taskgraph/loader/multi_dep.py
@@ -79,7 +79,7 @@ def loader(kind, path, config, params, loaded_tasks):
 
 
 def skip_only_or_not(config, task):
-    """Return True if we should skip this task based on only_ or not_ config."""
+    """Return True if we should skip this task based on `only_` or `not_` config."""
     only_platforms = config.get("only-for-build-platforms")
     not_platforms = config.get("not-for-build-platforms")
     only_attributes = config.get("only-for-attributes")
diff --git a/taskcluster/gecko_taskgraph/transforms/task.py b/taskcluster/gecko_taskgraph/transforms/task.py
index c087f47e92cc..f1d3e713f123 100644
--- a/taskcluster/gecko_taskgraph/transforms/task.py
+++ b/taskcluster/gecko_taskgraph/transforms/task.py
@@ -2082,7 +2082,7 @@ def chain_of_trust(config, tasks):
 @transforms.add
 def check_task_identifiers(config, tasks):
     """Ensures that all tasks have well defined identifiers:
-    ^[a-zA-Z0-9_-]{1,38}$
+    ``^[a-zA-Z0-9_-]{1,38}$``
     """
     e = re.compile("^[a-zA-Z0-9_-]{1,38}$")
     for task in tasks:
diff --git a/taskcluster/gecko_taskgraph/transforms/test/other.py b/taskcluster/gecko_taskgraph/transforms/test/other.py
index 717cc96036cd..de37292d807a 100644
--- a/taskcluster/gecko_taskgraph/transforms/test/other.py
+++ b/taskcluster/gecko_taskgraph/transforms/test/other.py
@@ -775,7 +775,7 @@ def set_test_setting(config, tasks):
     This transform adds a ``test-setting`` object to the ``extra`` portion of
     all test tasks, of the form:
 
-    .. code-block:: json
+    .. code-block::
 
         {
             "platform": { ... },
diff --git a/testing/mozbase/manifestparser/manifestparser/filters.py b/testing/mozbase/manifestparser/manifestparser/filters.py
index 36a1fd2edc14..659fe702e0d6 100644
--- a/testing/mozbase/manifestparser/manifestparser/filters.py
+++ b/testing/mozbase/manifestparser/manifestparser/filters.py
@@ -439,9 +439,11 @@ class tags(InstanceFilter):
 
 class failures(InstanceFilter):
     """
-    [test_foobar.html]
-    fail-if =
-      keyword # <comment>
+    .. code-block:: ini
+
+        [test_foobar.html]
+        fail-if =
+          keyword # <comment>
 
     :param keywords: A keyword to filter tests on
     """
diff --git a/testing/mozbase/mozdebug/mozdebug/mozdebug.py b/testing/mozbase/mozdebug/mozdebug/mozdebug.py
index 19f80f8d6a5a..beecc2cd9d30 100755
--- a/testing/mozbase/mozdebug/mozdebug/mozdebug.py
+++ b/testing/mozbase/mozdebug/mozdebug/mozdebug.py
@@ -132,15 +132,15 @@ def get_debugger_info(debugger, debuggerArgs=None, debuggerInteractive=False):
     """
     Get the information about the requested debugger.
 
-    Returns a dictionary containing the |path| of the debugger executable,
-    if it will run in |interactive| mode, its arguments and whether it needs
-    to escape arguments it passes to the debugged program (|requiresEscapedArgs|).
-    If the debugger cannot be found in the system, returns |None|.
+    Returns a dictionary containing the ``path`` of the debugger executable,
+    if it will run in ``interactive`` mode, its arguments and whether it needs
+    to escape arguments it passes to the debugged program (``requiresEscapedArgs``).
+    If the debugger cannot be found in the system, returns ``None``.
 
     :param debugger: The name of the debugger.
     :param debuggerArgs: If specified, it's the arguments to pass to the debugger,
-    as a string. Any debugger-specific separator arguments are appended after these
-    arguments.
+       as a string. Any debugger-specific separator arguments are appended after
+       these arguments.
     :param debuggerInteractive: If specified, forces the debugger to be interactive.
     """
 
@@ -217,8 +217,8 @@ def get_default_debugger_name(search=DebuggerSearch.OnlyFirst):
     Get the debugger name for the default debugger on current platform.
 
     :param search: If specified, stops looking for the debugger if the
-     default one is not found (|DebuggerSearch.OnlyFirst|) or keeps
-     looking for other compatible debuggers (|DebuggerSearch.KeepLooking|).
+     default one is not found (``DebuggerSearch.OnlyFirst``) or keeps
+     looking for other compatible debuggers (``DebuggerSearch.KeepLooking``).
     """
 
     mozinfo.find_and_update_from_json()
diff --git a/testing/mozbase/mozinfo/mozinfo/mozinfo.py b/testing/mozbase/mozinfo/mozinfo/mozinfo.py
index 667364f1ef3f..69510f7fef7b 100755
--- a/testing/mozbase/mozinfo/mozinfo/mozinfo.py
+++ b/testing/mozbase/mozinfo/mozinfo/mozinfo.py
@@ -280,7 +280,7 @@ def find_and_update_from_json(*dirs, **kwargs):
     :param tuple dirs: Directories in which to look for the file.
     :param dict kwargs: optional values:
                         raise_exception: if True, exceptions are raised.
-                                         False by default.
+                        False by default.
     :returns: None: default behavior if mozinfo.json cannot be found.
               json_path: string representation of mozinfo.json path.
     :raises: IOError: if raise_exception is True and file is not found.