Bug 1748845 - Add a custom mechanism to make some docs warnings fatal, r=ahal,firefox-source-docs-reviewers,sylvestre

The idea is to capture the warnings in a temporary file, and then
apply a set of regex to find any that should be treated as fatal.

This allows us to fix warnings one type at a time, and prevents us
regressing the warnings that are already fixed.

The "reference target not count" warning is added to the initial
forbidden list, so we can ensure we don't end up with internal links
pointing to nowhere.

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

docs/config.yml

@@ -93,3 +93,5 @@ redirects:
     tools/static-analysis/index.html: code-quality/static-analysis.html
     xpcom/xpcom: xpcom
 
+fatal warnings:
+    - "WARNING: '([^']*)' reference target not found:"

tools/moztreedocs/mach_commands.py

@@ -8,8 +8,10 @@ from __future__ import absolute_import, print_function, unicode_literals
 import fnmatch
 import multiprocessing
 import os
+import re
 import subprocess
 import sys
+import tempfile
 import time
 import yaml
 import uuid
@@ -160,16 +162,23 @@ def build_docs(
         # We want to verify if the links are valid or not
         fmt = "linkcheck"
 
-    result = _run_sphinx(docdir, savedir, fmt=fmt, jobs=jobs, verbose=verbose)
-    if result != 0:
+    status, warnings = _run_sphinx(docdir, savedir, fmt=fmt, jobs=jobs, verbose=verbose)
+    if status != 0:
         print(_dump_sphinx_backtrace())
         return die(
             "failed to generate documentation:\n"
-            "%s: sphinx return code %d" % (path, result)
+            "%s: sphinx return code %d" % (path, status)
         )
     else:
         print("\nGenerated documentation:\n%s" % savedir)
 
+    fatal_warnings = _check_sphinx_warnings(warnings)
+    if fatal_warnings:
+        return die(
+            "failed to generate documentation:\n "
+            f"Got fatal warnings:\n{''.join(fatal_warnings)}"
+        )
+
     # Upload the artifact containing the link to S3
     # This would be used by code-review to post the link to Phabricator
     if write_url is not None:
@@ -251,22 +260,43 @@ def _run_sphinx(docdir, savedir, config=None, fmt="html", jobs=None, verbose=Non
     # and makes the build generation very very very slow
     # So, disable it to generate the doc faster
     sentry_sdk.init(None)
-    args = [
-        "-T",
-        "-b",
-        fmt,
-        "-c",
-        os.path.dirname(config),
-        docdir,
-        savedir,
-    ]
-    if jobs:
-        args.extend(["-j", jobs])
-    if verbose:
-        args.extend(["-v", "-v"])
-    print("Run sphinx with:")
-    print(args)
-    return sphinx.cmd.build.build_main(args)
+    warn_fd, warn_path = tempfile.mkstemp()
+    os.close(warn_fd)
+    try:
+        args = [
+            "-T",
+            "-b",
+            fmt,
+            "-c",
+            os.path.dirname(config),
+            "-w",
+            warn_path,
+            docdir,
+            savedir,
+        ]
+        if jobs:
+            args.extend(["-j", jobs])
+        if verbose:
+            args.extend(["-v", "-v"])
+        print("Run sphinx with:")
+        print(args)
+        status = sphinx.cmd.build.build_main(args)
+        with open(warn_path) as warn_file:
+            warnings = warn_file.readlines()
+        return status, warnings
+    finally:
+        os.unlink(warn_path)
+
+
+def _check_sphinx_warnings(warnings):
+    with open(os.path.join(DOC_ROOT, "config.yml"), "r") as fh:
+        fatal_warnings_src = yaml.safe_load(fh)["fatal warnings"]
+    fatal_warnings_regex = [re.compile(item) for item in fatal_warnings_src]
+    fatal_warnings = []
+    for warning in warnings:
+        if any(item.search(warning) for item in fatal_warnings_regex):
+            fatal_warnings.append(warning)
+    return fatal_warnings
 
 
 def manager():