Bug 1917163 - Update rstcheck to 6.2.4, fix resulting errors in docum…

…ents, r=Standard8

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

.rstcheck.cfg

@@ -1,7 +1,25 @@
+# Reference: https://rstcheck.readthedocs.io/en/latest/usage/config/#ini-format
 [rstcheck]
-# See: https://rstcheck.readthedocs.io/en/latest/usage/config/#ini-format
-# Note that the version used in mozilla-central is behind, so not all options
-# are available.
-#
-ignore_language=cpp,json
-ignore_messages=(No Pygments lexer found for "none".)
+# This list might be simplified when https://github.com/rstcheck/rstcheck-core/issues/68
+# is fixed.
+ignore_directives=
+    autoclass,
+    autoexception,
+    automethod,
+    automodule,
+    digraph,
+    dropdown,
+    graph,
+    graphviz,
+    js,
+    js:autoclass,
+    js:autofunction,
+    mermaid,
+ignore_languages =
+    cpp,
+    json,
+ignore_messages=(Duplicate explicit target name: "(.*)"|Enumerated list start value not ordinal\-1: "\d" \(ordinal \d\)|Hyperlink target ".*" is not referenced\.|No Pygments lexer found for "none"\.)
+ignore_roles =
+    js,
+    ref,
+    searchfox,

build/docs/defining-xpcom-components.rst

@@ -208,6 +208,7 @@ Class Constructors
 This simplest way to define a component is to include a header defining a
 concrete type, and let the component manager call that class's constructor:
 
+.. rstcheck: ignore-languages=python
 .. code-block:: python
 
   'type': 'mozilla::foo::Foo',
@@ -226,6 +227,7 @@ returns the same instance on subsequent calls. This requires declaring the
 constructor in an included header, and implementing it in a separate source
 file:
 
+.. rstcheck: ignore-languages=python
 .. code-block:: python
 
   'type': 'mozilla::foo::Foo',
@@ -255,6 +257,7 @@ External Constructors
 For types whose headers can't easily be included, constructors can be defined
 using a template specialization on an incomplete type:
 
+.. rstcheck: ignore-languages=python
 .. code-block:: python
 
   'type': 'mozilla::foo::Foo',
@@ -281,6 +284,7 @@ Registering Categories
 Classes which need define category entries with the same value as their
 contract ID may do so using the following:
 
+.. rstcheck: ignore-languages=python
 .. code-block:: python
 
     'contract_ids': ['@mozilla.org/foo;1'],

build/docs/mozbuild-symbols.rst

@@ -4,4 +4,5 @@
 mozbuild Sandbox Symbols
 ========================
 
+.. rstcheck: ignore-directives=mozbuildsymbols
 .. mozbuildsymbols:: mozbuild.frontend.context

build/docs/test_manifests.rst

@@ -198,6 +198,7 @@ See
 `the source <https://hg.mozilla.org/mozilla-central/file/default/testing/mozbase/manifestparser/manifestparser/manifestparser.py>`_ for the full documentation of the
 expression syntax until it is documented here.
 
+.. rstcheck: ignore-directives=todo
 .. todo::
 
    Document manifest filter language.

devtools/docs/user/devtoolsapi/index.rst

@@ -669,6 +669,7 @@ ToolSidebar
 
 To build a sidebar in your tool, first, add a xul:tabbox where you want the sidebar to live:
 
+.. rstcheck: ignore-languages=xml
 .. code-block:: xml
 
   <splitter class="devtools-side-splitter"/>

docs/bug-mgmt/guides/status-flags.rst

@@ -1,22 +1,24 @@
 Release Status Flags
 ====================
 
-The flag ``status_firefoxNN`` has many values, here’s a cheat sheet.
+The flag ``status_firefoxN`` has many values, here’s a cheat sheet.
 
-== ========== ========== ============ =================
-—  ?          unaffected affected     fixed
-== ========== ========== ============ =================
-?  unaffected            wontfix      verified
-\  affected              fix-optional disabled
-\                        fixed        verified disabled
-== ========== ========== ============ =================
++---------+------------+------------+--------------+-------------------+
+| \-\-\-  | \?         | unaffected | affected     | fixed             |
++=========+============+============+==============+===================+
+| \?      | unaffected |            | wontfix      | verified          |
++---------+------------+------------+--------------+-------------------+
+|         | affected   |            | fix-optional | disabled          |
++---------+------------+------------+--------------+-------------------+
+|         |            |            | fixed        | verified disabled |
++---------+------------+------------+--------------+-------------------+
 
 The headers of the table are values of the status flag. Each column are
 the states reachable from the column headings.
 
 -  ``---`` we don’t know whether Firefox N is affected
 -  ``?`` we don’t know whether Firefox N is affected, but we want to find
-   out.
+   out
 -  ``affected`` - present in this release
 -  ``unaffected`` - not present in this release
 -  ``fixed`` - a contributor has landed a change set in the tree

intl/l10n/docs/fluent/index.rst

@@ -2,8 +2,9 @@
 Fluent
 ======
 
-`Fluent`_ is a localization system developed by Mozilla, which aims to replace
-all existing localization models currently used at Mozilla.
+`Fluent <http://projectfluent.org/>`__ is a localization system developed by
+Mozilla, which aims to replace all existing localization models currently used
+at Mozilla.
 
 In case of Firefox it directly supersedes DTD and StringBundle systems, providing
 a large number of features and improvements over both of them, for developers
@@ -21,5 +22,3 @@ Other resources:
  * `Fluent Wiki <https://github.com/projectfluent/fluent/wiki>`_
  * `Fluent.js Wiki <https://github.com/projectfluent/fluent.js/wiki>`_
  * `Fluent DOM L10n Tutorial <https://projectfluent.org/dom-l10n-documentation/>`_
-
-.. _Fluent: http://projectfluent.org/

mobile/android/docs/geckoview/contributor/geckoview-architecture.rst

@@ -392,6 +392,7 @@ be declared in GeckoView's ``AndroidManifest.xml``.
 
 For example, this is the definition of the ``media`` process:
 
+.. rstcheck: ignore-languages=xml
 .. code-block:: xml
 
   <service

mobile/android/docs/geckoview/contributor/geckoview-quick-start.rst

@@ -326,7 +326,7 @@ To view the javadoc locally, choose one of the two options:
 
   .. code:: bash
 
-     cd <path_of_javadoc_from_above>
+     cd path_of_javadoc_from_above
 
 Now, we want to launch a local web server. To launch locally, use any web server, for example:
 

python/mach/docs/commands.rst

@@ -35,12 +35,13 @@ The important decorators are as follows:
 
 Here is a complete example:
 
+.. rstcheck: ignore-languages=python
 .. code-block:: python
 
-   from mach.decorators import (
-       CommandArgument,
-       Command,
-   )
+    from mach.decorators import (
+      CommandArgument,
+      Command,
+    )
 
     @Command('doit', help='Do ALL OF THE THINGS.')
     @CommandArgument('--force', '-f', action='store_true',
@@ -77,19 +78,20 @@ why the command cannot currently be run.
 
 Here is an example:
 
+.. rstcheck: ignore-languages=python
 .. code-block:: python
 
-   from mach.decorators import (
-       Command,
-   )
+  from mach.decorators import (
+      Command,
+  )
 
-   def build_available(cls):
-       """The build needs to be available."""
-       return cls.build_path is not None
+  def build_available(cls):
+      """The build needs to be available."""
+      return cls.build_path is not None
 
-   @Command('run_tests', conditions=[build_available])
-   def run_tests(command_context):
-       # Do stuff here.
+  @Command('run_tests', conditions=[build_available])
+  def run_tests(command_context):
+      # Do stuff here.
 
 By default all commands without any conditions applied will be runnable,
 but it is possible to change this behaviour by setting

python/mozbuild/mozbuild/vendor/docs/index.rst

@@ -27,6 +27,7 @@ to interact with it.
 Template ``moz.yaml`` file
 ==========================
 
+.. rstcheck: ignore-languages=yaml
 .. code-block:: yaml
 
 

testing/condprofile/README.rst

@@ -100,7 +100,9 @@ and they provide four keys:
 In the example below, we install uBlock, set a pref, and pass the
 **max_urls** option to the **heavy** scenario.
 
-  {
+.. code-block:: json
+
+   {
       "name": "intermediate",
       "addons":{
          "uBlock":"https://addons.mozilla.org/firefox/downloads/file/3361355/ublock_origin-1.21.2-an+fx.xpi"

testing/mozbase/docs/manifestparser.rst

@@ -306,6 +306,7 @@ that can be applied to the `TestManifest`. To do so, add the filter to `TestMani
     :members:
     :exclude-members: filterlist,InstanceFilter,DEFAULT_FILTERS
 
+.. rstcheck: ignore-directives=autodata
 .. autodata::  manifestparser.filters.DEFAULT_FILTERS
     :annotation:
 

testing/mozbase/docs/mozproxy.rst

@@ -11,7 +11,9 @@ Mozproxy is used by Raptor to run performance test without having to interact
 with the real web site.
 
 Mozproxy provide a function that returns a playback class. The usage pattern is
-::
+
+.. rstcheck: ignore-languages=python
+.. code-block:: python
 
    from mozproxy import get_playback
 

testing/mozharness/docs/mozharness.mozilla.rst

@@ -22,7 +22,7 @@ mozharness.mozilla.blob_upload module
     :show-inheritance:
 
 mozharness.mozilla.automation module
-----------------------------------
+------------------------------------
 
 .. automodule:: mozharness.mozilla.automation
     :members:

toolkit/components/telemetry/docs/collection/scalars.rst

@@ -116,6 +116,7 @@ definition file.
 
 The probes in the definition file are represented in a fixed-depth, two-level structure:
 
+.. rstcheck: ignore-languages=yaml
 .. code-block:: yaml
 
     # The following is a category.

toolkit/modules/docs/AsyncShutdown.rst

@@ -237,7 +237,7 @@ 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);
 - ``webWorkersShutdown`` (once this phase is complete, JavaScript does not have access to workers anymore);
-- ...
+- …
 
 Much as services, phases have clients. For instance, all users of web workers MUST have finished using their web workers before the end of phase ``webWorkersShutdown``.
 

tools/lint/rst/__init__.py

@@ -39,9 +39,6 @@
 )
 
 RSTCHECK_FORMAT_REGEX = re.compile(r"(.*):(.*): \(.*/([0-9]*)\) (.*)$")
-IGNORE_NOT_REF_LINK_UPSTREAM_BUG = re.compile(
-    r"Hyperlink target (.*) is not referenced."
-)
 
 
 def setup(root, **lintargs):
@@ -69,6 +66,8 @@ def get_rstcheck_binary():
 
 def parse_with_split(errors):
     match = RSTCHECK_FORMAT_REGEX.match(errors)
+    if not match:
+        return None
     filename, lineno, level, message = match.groups()
 
     return filename, lineno, level, message
@@ -81,15 +80,10 @@ def lint(files, config, **lintargs):
     paths = list(paths)
     chunk_size = 50
     binary = get_rstcheck_binary()
-    # rstcheck configuration is stored in `/.rstcheck.cfg`. The `ignore-roles`
-    # directive remains in this file as it doesn't have effect when declared in
-    # the config file.
-    rstcheck_options = [
-        "--ignore-roles=searchfox",
-    ]
 
     while paths:
-        cmdargs = [which("python"), binary] + rstcheck_options + paths[:chunk_size]
+        # Config for rstcheck is stored in `/.rstcheck.cfg`.
+        cmdargs = [which("python"), binary] + paths[:chunk_size]
         log.debug("Command: {}".format(" ".join(cmdargs)))
 
         proc = subprocess.Popen(
@@ -102,10 +96,9 @@ def lint(files, config, **lintargs):
         all_errors = proc.communicate()[1]
         for errors in all_errors.split("\n"):
             if len(errors) > 1:
-                filename, lineno, level, message = parse_with_split(errors)
-                if not IGNORE_NOT_REF_LINK_UPSTREAM_BUG.match(message):
-                    # Ignore an upstream bug
-                    # https://github.com/rstcheck/rstcheck-core/issues/4
+                split_result = parse_with_split(errors)
+                if split_result:
+                    filename, lineno, level, message = split_result
                     res = {
                         "path": filename,
                         "message": message,

tools/lint/rst/requirements.in

@@ -12,7 +12,7 @@ snowballstemmer==2.2.0
 sphinxcontrib-applehelp==1.0.4
 sphinxcontrib-htmlhelp==2.0.1
 sphinxcontrib-mermaid==0.9.2
-rstcheck==3.5.0
+rstcheck==6.2.4
 Pygments==2.14.0
 pytz==2022.7.1
 urllib3==1.26.9