Utilities/Sphinx: Fix parallel documentation builds

In commit d78bfa1ecc (Utilities/Sphinx: support cmakedomain running in
parallel, 2022-10-24, v3.26.0-rc1~495^2) we declared the domain as
parallel-safe without actually implementing the required
`merge_domaindata` method.  Since then, commit 37e015d4a6
(Utilities/Sphinx: Refactor Sphinx reference recording) changed how we
store resolved references, such that our separate fix for 3.26 does not
work in 3.27+.

While at it, correct a crusty comment that was overlooked during the
aforementioned refactoring.

Issue: #24076
Co-authored-by: Jared Dillard <jared.dillard@gmail.com>

1 files changed, 15 insertions, 1 deletions

diff --git a/Utilities/Sphinx/cmake.py b/Utilities/Sphinx/cmake.py
index 0afd705..67dcec7 100644
--- a/Utilities/Sphinx/cmake.py
+++ b/Utilities/Sphinx/cmake.py
@@ -668,7 +668,7 @@ class CMakeDomain(Domain):
         'manual':     CMakeXRefRole(),
     }
     initial_data = {
-        'objects': {},  # fullname -> docname, objtype
+        'objects': {},  # fullname -> ObjectEntry
     }
 
     def clear_doc(self, docname):
@@ -679,6 +679,20 @@ class CMakeDomain(Domain):
         for fullname in to_clear:
             del self.data['objects'][fullname]
 
+    def merge_domaindata(self, docnames, otherdata):
+        """Merge domaindata from the workers/chunks when they return.
+
+        Called once per parallelization chunk.
+        Only used when sphinx is run in parallel mode.
+
+        :param docnames: a Set of the docnames that are part of the current
+                         chunk to merge
+        :param otherdata: the partial data calculated by the current chunk
+        """
+        for refname, obj in otherdata['objects'].items():
+            if obj.docname in docnames:
+                self.data['objects'][refname] = obj
+
     def resolve_xref(self, env, fromdocname, builder,
                      typ, target, node, contnode):
         targetid = f'{typ}:{target}'