translator: register section anchors for all editors

To help ensure anchor links to section work across all editor types and
on all Confluence variants, ensure we always inject section anchors.

Historically, this extension would only create anchors if required.
Sections should have their own identifiers pre-made by Confluence.
However, the identifiers are not consistent between different variations
of Confluence and certain features (e.g. ac:links to anchors) expect
certain anchor names. Over time we duplicated some anchors to help make
things smooth when the new Confluence editor was made. Unfortunately,
recent testing still showed not all links would function as expected.
This commit tries to cover all anchor cases by always forcefully
creating anchors in sections (and compatibility anchors), no matter
what the editor is. When testing on Confluence Data Center, references
appeared to work as they always have. With Confluence Cloud, references
appear to function across different editors with when checking
reference tests and inspecting `contents` usage.

Signed-off-by: James Knight <git@jdknight.me>

Author: jdknight

sphinxcontrib/confluencebuilder/storage/translator.py

@@ -273,21 +273,22 @@ def visit_title(self, node):
             else:
                 docname = self.docname
 
-            # For v2, will will generate section anchors inside the title
-            # area for the following reasons:
+            # Generate section anchors inside the title area for the following
+            # reasons:
             # - We want to create inside the header inside if we input anchors
             #    before the header, it increase the space above the anchor
             #    due to how v2 styles a page.
             # - We are generating compatible anchor links (prefixed with the
             #    repsective document name) which helps allow `ac:link` macros
             #    properly link when coming from v1 or v2 editor pages.
-            if self.v2 and 'names' in node.parent:
+            # - Helps support anchor links for legacy editor on Confluence Cloud
+            if 'names' in node.parent:
                 for name in node.parent['names']:
                     anchor = name.replace(' ', '-')
                     target_name = f'{docname}/#{anchor}'
                     target = self.state.target(target_name)
                     if target and target not in new_targets:
-                        self._build_anchor(node, target)
+                        self._build_anchor(node, target, force_compat=True)
                         new_targets.append(target)
 
             # For MyST sections with an auto-generated slug, we will use this
@@ -3497,7 +3498,7 @@ def _build_id_anchors(self, node):
             for id_ in node['ids']:
                 self._build_anchor(node, id_)
 
-    def _build_anchor(self, node, anchor):
+    def _build_anchor(self, node, anchor, *, force_compat=False):
         """
         build an anchor on a page
 
@@ -3514,14 +3515,15 @@ def _build_anchor(self, node, anchor):
         Args:
             node: the node adding the anchor
             anchor: the name of the anchor to create
+            force_compat (optional): always force compat anchor
         """
 
         self.verbose(f'build anchor ({self.docname}): {anchor}')
         self.body.append(self.start_ac_macro(node, 'anchor'))
         self.body.append(self.build_ac_param(node, '', anchor))
         self.body.append(self.end_ac_macro(node, suffix=''))
 
-        if self.v2:
+        if self.builder.cloud or self.v2 or force_compat:
             doctitle = self.state.title(self.docname)
             doctitle = self.encode(doctitle.replace(' ', ''))