Merge pull request #950 from sphinx-contrib/restore-missing-anchor-links

Restore missing anchor links (autodocs and math)

Author: jdknight

sphinxcontrib/confluencebuilder/storage/translator.py

@@ -297,15 +297,15 @@ def visit_paragraph(self, node):
 
         self.body.append(self._start_tag(node, 'p', **attribs))
 
-        # For any names assigned to a paragraph, generate an anchor link to
-        # ensure content can jump to this specific paragraph. This was
-        # originally handled in `visit_target`, but now applied here since in
-        # v2, anchors need to be inside paragraphs to prevent any undesired
-        # extra spacing above the paragraph (before or after for v1, there is
-        # no difference).
-        if 'names' in node:
-            for anchor in node['names']:
-                self._build_anchor(node, anchor)
+        # build anchors for ids which references may want to link to
+        #
+        # This was originally handled in `visit_target`, but moved into this
+        # section since in v2, anchors need to be inside paragraphs to prevent
+        # any undesired extra spacing above the paragraph (before or after for
+        # v1, there is no difference). We also used to use `names` over `ids`
+        # which worked for most things; however, some autodocs links seemed to
+        # use some id-only targets instead.
+        self._build_id_anchors(node)
 
         self.context.append(self._end_tag(node, suffix=''))
 
@@ -517,9 +517,7 @@ def visit_term(self, node):
                 **{'style': f'margin-left: {offset}px;'}))
             self.context.append(self._end_tag(node))
 
-        if 'ids' in node:
-            for id_ in node['ids']:
-                self._build_anchor(node, id_)
+        self._build_id_anchors(node)
 
         if not self.v2:
             self.body.append(self._start_tag(node, 'dt'))
@@ -1431,9 +1429,7 @@ def visit_target(self, node):
         # build an anchor link for them; example cases include documentation
         # which generate a custom anchor link inside a paragraph
         if 'ids' in node and 'refuri' not in node:
-            for id_ in node['ids']:
-                self._build_anchor(node, id_)
-
+            self._build_id_anchors(node)
             self.body.append(self.encode(node.astext()))
 
         raise nodes.SkipNode
@@ -1805,9 +1801,9 @@ def _visit_image(self, node, opts):
             self.context.append(self._end_tag(node))
 
             self.body.append(self._start_tag(node, 'ac:layout-cell'))
-            if 'ids' in node:
-                for id_ in node['ids']:
-                    self._build_anchor(node, id_)
+
+            self._build_id_anchors(node)
+
             self.body.append(self._end_tag(node))
 
             self.body.append(self._start_tag(node, 'ac:layout-cell'))
@@ -3093,6 +3089,28 @@ def visit_raw(self, node):
     # #                                                                        #
     # ##########################################################################
 
+    def _build_id_anchors(self, node):
+        """
+        build anchors for a node that has any ids
+
+        A node may define one more more identifiers through an `ids` list.
+        For some nodes, it may be ideal to generate anchor links for each
+        identifier listed, which may be used by other nodes to link to. For
+        example, a paragraph may have multiple identifiers assigned to it,
+        which features like autotools may want to jump to said paragraph.
+
+        Note all use cases where a node has an identifier will need to build
+        an anchor (so, it is not done automatically). This call can be used
+        to explicitly build anchors on nodes that require it.
+
+        Args:
+            node: the node to generate anchors on
+        """
+
+        if 'ids' in node:
+            for id_ in node['ids']:
+                self._build_anchor(node, id_)
+
     def _build_anchor(self, node, anchor):
         """
         build an anchor on a page

tests/unit-tests/datasets/rst/math/index.rst

@@ -0,0 +1,7 @@
+.. https://docutils.sourceforge.io/docs/ref/rst/directives.html#math
+
+math
+----
+
+.. math:: e^{i\pi} + 1 = 0
+    :label: euler

tests/unit-tests/test_rst_math.py

@@ -0,0 +1,57 @@
+# SPDX-License-Identifier: BSD-2-Clause
+# Copyright Sphinx Confluence Builder Contributors (AUTHORS)
+
+from tests.lib.parse import parse
+from tests.lib.testcase import ConfluenceTestCase
+from tests.lib.testcase import setup_builder
+from tests.lib.testcase import setup_editor
+import shutil
+import unittest
+
+
+class TestConfluenceRstMath(ConfluenceTestCase):
+    @classmethod
+    def setUpClass(cls):
+        # math images need latex to create
+        if not shutil.which('latex'):
+            msg = 'latex not installed'
+            raise unittest.SkipTest(msg)
+
+        super().setUpClass()
+
+        cls.dataset = cls.datasets / 'rst' / 'math'
+
+    @setup_builder('confluence')
+    def test_storage_rst_math_v1_default(self):
+        out_dir = self.build(self.dataset)
+
+        with parse('index', out_dir) as data:
+            images = data.find_all('ac:image')
+            self.assertIsNotNone(images)
+            self.assertEqual(len(images), 1)
+
+            # sanity check anchor creation
+            anchor_tag = data.find('ac:structured-macro',
+                {'ac:name': 'anchor'})
+            self.assertIsNotNone(anchor_tag)
+            anchor_param = anchor_tag.find('ac:parameter')
+            self.assertIsNotNone(anchor_param)
+            self.assertEqual(anchor_param.text, 'equation-euler')
+
+    @setup_builder('confluence')
+    @setup_editor('v2')
+    def test_storage_rst_math_v2_default(self):
+        out_dir = self.build(self.dataset)
+
+        with parse('index', out_dir) as data:
+            images = data.find_all('ac:image')
+            self.assertIsNotNone(images)
+            self.assertEqual(len(images), 1)
+
+            # sanity check anchor creation
+            anchor_tag = data.find('ac:structured-macro',
+                {'ac:name': 'anchor'})
+            self.assertIsNotNone(anchor_tag)
+            anchor_param = anchor_tag.find('ac:parameter')
+            self.assertIsNotNone(anchor_param)
+            self.assertEqual(anchor_param.text, 'equation-euler')