Bug 1780087 - [docs] Implement a 'searchfox' role, r=firefox-source-docs-reviewers,sylvestre

See the docstring in this patch for usage examples.

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

python/mozbuild/mozbuild/sphinx.py

@@ -2,12 +2,12 @@
 # License, v. 2.0. If a copy of the MPL was not distributed with this
 # file, You can obtain one at http://mozilla.org/MPL/2.0/.
 
-from __future__ import absolute_import, print_function
-
 import importlib
 
+from docutils import nodes
 from docutils.parsers.rst import Directive
 from sphinx.util.docstrings import prepare_docstring
+from sphinx.util.docutils import ReferenceRole
 
 
 def function_reference(f, attr, args, doc):
@@ -195,10 +195,52 @@ class MozbuildSymbols(Directive):
         return []
 
 
+class Searchfox(ReferenceRole):
+    """Role which links a relative path from the source to it's searchfox URL.
+
+    Can be used like:
+
+        See :searchfox:`browser/base/content/browser-places.js` for more details.
+
+    Will generate a link to
+    ``https://searchfox.org/mozilla-central/source/browser/base/content/browser-places.js``
+
+    The example above will use the path as the text, to use custom text:
+
+        See :searchfox:`this file <browser/base/content/browser-places.js>` for
+        more details.
+
+    To specify a different source tree:
+
+        See :searchfox:`mozilla-beta:browser/base/content/browser-places.js`
+        for more details.
+    """
+
+    def run(self):
+        base = "https://searchfox.org/{source}/source/{path}"
+
+        if ":" in self.target:
+            source, path = self.target.split(":", 1)
+        else:
+            source = "mozilla-central"
+            path = self.target
+
+        url = base.format(source=source, path=path)
+
+        if self.has_explicit_title:
+            title = self.title
+        else:
+            title = path
+
+        node = nodes.reference(self.rawtext, title, refuri=url, **self.options)
+        return [node], []
+
+
 def setup(app):
     from moztreedocs import manager
 
     app.add_directive("mozbuildsymbols", MozbuildSymbols)
+    app.add_role("searchfox", Searchfox())
 
     # Unlike typical Sphinx installs, our documentation is assembled from
     # many sources and staged in a common location. This arguably isn't a best

tools/lint/rst/__init__.py

@@ -81,10 +81,13 @@ def lint(files, config, **lintargs):
     paths = list(paths)
     chunk_size = 50
     binary = get_rstcheck_binary()
-    rstcheck_options = "--ignore-language=cpp,json"
+    rstcheck_options = [
+        "--ignore-language=cpp,json",
+        "--ignore-roles=searchfox",
+    ]
 
     while paths:
-        cmdargs = [which("python"), binary, rstcheck_options] + paths[:chunk_size]
+        cmdargs = [which("python"), binary] + rstcheck_options + paths[:chunk_size]
         log.debug("Command: {}".format(" ".join(cmdargs)))
 
         proc = subprocess.Popen(