[PATCH 5/9] docs: maintainers_include.py: clean most SPHINXDIRS=process warnings

[Mauro Carvalho Chehab]

building docs with SPHINXDIRS=process is too noisy, as it
generates lots of undefined refs. Fixing it is easy: just let
linkify generate html URLs for the broken links when SPHINXDIRS
is used.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@xxxxxxxxxx>
---
 Documentation/sphinx/maintainers_include.py | 21 +++++++++++++++++++--
 1 file changed, 19 insertions(+), 2 deletions(-)

diff --git a/Documentation/sphinx/maintainers_include.py b/Documentation/sphinx/maintainers_include.py
index 4fc894b377e6..1d7d441e281c 100755
--- a/Documentation/sphinx/maintainers_include.py
+++ b/Documentation/sphinx/maintainers_include.py
@@ -104,10 +104,27 @@ class MaintainersParser:
 
     def linkify(self, text):
         """Linkify all non-wildcard refs to ReST files in Documentation/"""
+
         m = self.re_doc.search(text)
         if m:
-            # maintainers.rst is in a subdirectory, so include "../".
-            text = self.re_doc.sub(':doc:`%s <../%s>`' % (m.group(2), m.group(2)), text)
+            fname = m.group(1)
+            name = m.group(2)
+            ename = "/" + name
+
+            entry = os.path.relpath(self.base_dir + ename, self.app_dir)
+            full_name = os.path.join(self.base_dir, fname)
+            path = os.path.relpath(full_name, self.app_dir)
+
+            #
+            # When SPHINXDIRS is used, it will try to reference files
+            # outside srctree, causing warnings. To avoid that, point
+            # to the latest official documentation
+            #
+            if path.startswith("../"):
+                html = KERNELDOC_URL + m.group(2) + ".html"
+                text = self.re_doc.sub(f'`{name} <{html}>_`', text)
+            else:
+                text = self.re_doc.sub(f':doc:`{name} <{entry}>`', text)
 
         return text
 
-- 
2.54.0