Be more ephemeral (in anchor link title text)

Author: AA-Turner

CHANGES

@@ -65,6 +65,7 @@ Bugs fixed
 * #10795: Raise a descriptive error if ``graphviz_dot`` is falsy.
 * #11546: Translated nodes identical to their original text are now marked
   with the ``translated=True`` attribute.
+* #10049: html: Change "Permalink" to "Link" for title text in link anchors.
 
 Testing
 -------

doc/usage/configuration.rst

@@ -1278,15 +1278,15 @@ that use Sphinx's HTMLWriter class.
 
 .. confval:: html_permalinks
 
-   If true, Sphinx will add "permalinks" for each heading and description
-   environment.  Default: ``True``.
+   Add link anchors for each heading and description environment.
+   Default: ``True``.
 
    .. versionadded:: 3.5
 
 .. confval:: html_permalinks_icon
 
-   A text for permalinks for each heading and description environment.  HTML
-   tags are allowed.  Default: a paragraph sign; ``¶``
+   Text for link anchors for each heading and description environment.
+   HTML entities and Unicode are allowed.  Default: a paragraph sign; ``¶``
 
    .. versionadded:: 3.5
 

sphinx/ext/imgmath.py

@@ -362,7 +362,7 @@ def html_visit_displaymath(self: HTML5Translator, node: nodes.math_block) -> Non
     if node['number']:
         number = get_node_equation_number(self, node)
         self.body.append('<span class="eqno">(%s)' % number)
-        self.add_permalink_ref(node, _('Permalink to this equation'))
+        self.add_permalink_ref(node, _('Link to this equation'))
         self.body.append('</span>')
 
     if rendered_path is None:

sphinx/ext/mathjax.py

@@ -46,7 +46,7 @@ def html_visit_displaymath(self: HTML5Translator, node: nodes.math_block) -> Non
     if node['number']:
         number = get_node_equation_number(self, node)
         self.body.append('<span class="eqno">(%s)' % number)
-        self.add_permalink_ref(node, _('Permalink to this equation'))
+        self.add_permalink_ref(node, _('Link to this equation'))
         self.body.append('</span>')
     self.body.append(self.builder.config.mathjax_display[0])
     parts = [prt for prt in node.astext().split('\n\n') if prt.strip()]

sphinx/writers/html5.py

@@ -96,7 +96,7 @@ def visit_desc_signature(self, node: Element) -> None:
     def depart_desc_signature(self, node: Element) -> None:
         self.protect_literal_text -= 1
         if not node.get('is_multiline'):
-            self.add_permalink_ref(node, _('Permalink to this definition'))
+            self.add_permalink_ref(node, _('Link to this definition'))
         self.body.append('</dt>\n')
 
     def visit_desc_signature_line(self, node: Element) -> None:
@@ -105,7 +105,7 @@ def visit_desc_signature_line(self, node: Element) -> None:
     def depart_desc_signature_line(self, node: Element) -> None:
         if node.get('add_permalink'):
             # the permalink info is on the parent desc_signature node
-            self.add_permalink_ref(node.parent, _('Permalink to this definition'))
+            self.add_permalink_ref(node.parent, _('Link to this definition'))
         self.body.append('<br />')
 
     def visit_desc_content(self, node: Element) -> None:
@@ -409,10 +409,11 @@ def append_fignumber(figtype: str, figure_id: str) -> None:
                 append_fignumber(figtype, node['ids'][0])
 
     def add_permalink_ref(self, node: Element, title: str) -> None:
+        icon = self.config.html_permalinks_icon
         if node['ids'] and self.config.html_permalinks and self.builder.add_permalinks:
-            format = '<a class="headerlink" href="#%s" title="%s">%s</a>'
-            self.body.append(format % (node['ids'][0], title,
-                                       self.config.html_permalinks_icon))
+            self.body.append(
+                f'<a class="headerlink" href="#{node["ids"][0]}" title="{title}">{icon}</a>',
+            )
 
     # overwritten
     def visit_bullet_list(self, node: Element) -> None:
@@ -457,7 +458,7 @@ def depart_term(self, node: Element) -> None:
         else:
             if isinstance(node.parent.parent.parent, addnodes.glossary):
                 # add permalink if glossary terms
-                self.add_permalink_ref(node, _('Permalink to this term'))
+                self.add_permalink_ref(node, _('Link to this term'))
 
             self.body.append('</dt>')
 
@@ -480,16 +481,16 @@ def depart_title(self, node: Element) -> None:
                 node.parent.hasattr('ids') and node.parent['ids']):
             # add permalink anchor
             if close_tag.startswith('</h'):
-                self.add_permalink_ref(node.parent, _('Permalink to this heading'))
+                self.add_permalink_ref(node.parent, _('Link to this heading'))
             elif close_tag.startswith('</a></h'):
                 self.body.append('</a><a class="headerlink" href="#%s" ' %
                                  node.parent['ids'][0] +
                                  'title="{}">{}'.format(
-                                     _('Permalink to this heading'),
+                                     _('Link to this heading'),
                                      self.config.html_permalinks_icon))
             elif isinstance(node.parent, nodes.table):
                 self.body.append('</span>')
-                self.add_permalink_ref(node.parent, _('Permalink to this table'))
+                self.add_permalink_ref(node.parent, _('Link to this table'))
         elif isinstance(node.parent, nodes.table):
             self.body.append('</span>')
 
@@ -532,11 +533,11 @@ def depart_caption(self, node: Element) -> None:
 
         # append permalink if available
         if isinstance(node.parent, nodes.container) and node.parent.get('literal_block'):
-            self.add_permalink_ref(node.parent, _('Permalink to this code'))
+            self.add_permalink_ref(node.parent, _('Link to this code'))
         elif isinstance(node.parent, nodes.figure):
-            self.add_permalink_ref(node.parent, _('Permalink to this image'))
+            self.add_permalink_ref(node.parent, _('Link to this image'))
         elif node.parent.get('toctree'):
-            self.add_permalink_ref(node.parent.parent, _('Permalink to this toctree'))
+            self.add_permalink_ref(node.parent.parent, _('Link to this toctree'))
 
         if isinstance(node.parent, nodes.container) and node.parent.get('literal_block'):
             self.body.append('</div>\n')

tests/test_build_html.py

@@ -1345,7 +1345,7 @@ def test_html_anchor_for_figure(app):
     app.builder.build_all()
     content = (app.outdir / 'index.html').read_text(encoding='utf8')
     assert ('<figcaption>\n<p><span class="caption-text">The caption of pic</span>'
-            '<a class="headerlink" href="#id1" title="Permalink to this image">¶</a></p>\n</figcaption>'
+            '<a class="headerlink" href="#id1" title="Link to this image">¶</a></p>\n</figcaption>'
             in content)
 
 
@@ -1722,7 +1722,7 @@ def test_html_permalink_icon(app):
 
     assert ('<h1>The basic Sphinx documentation for testing<a class="headerlink" '
             'href="#the-basic-sphinx-documentation-for-testing" '
-            'title="Permalink to this heading"><span>[PERMALINK]</span></a></h1>' in content)
+            'title="Link to this heading"><span>[PERMALINK]</span></a></h1>' in content)
 
 
 @pytest.mark.sphinx('html', testroot='html_signaturereturn_icon')
@@ -1769,7 +1769,7 @@ def test_option_emphasise_placeholders(app, status, warning):
             '<em><span class="pre">COUNT</span></em>' in content)
     assert '<span class="pre">{{value}}</span>' in content
     assert ('<span class="pre">--plugin.option</span></span>'
-            '<a class="headerlink" href="#cmdoption-perl-plugin.option" title="Permalink to this definition">¶</a></dt>') in content
+            '<a class="headerlink" href="#cmdoption-perl-plugin.option" title="Link to this definition">¶</a></dt>') in content
 
 
 @pytest.mark.sphinx('html', testroot='root')
@@ -1781,7 +1781,7 @@ def test_option_emphasise_placeholders_default(app, status, warning):
     assert '<span class="pre">{client_name}</span>' in content
     assert ('<span class="pre">--plugin.option</span></span>'
             '<span class="sig-prename descclassname"></span>'
-            '<a class="headerlink" href="#cmdoption-perl-plugin.option" title="Permalink to this definition">¶</a></dt>') in content
+            '<a class="headerlink" href="#cmdoption-perl-plugin.option" title="Link to this definition">¶</a></dt>') in content
 
 
 @pytest.mark.sphinx('html', testroot='root')

tests/test_directive_code.py

@@ -323,7 +323,7 @@ def test_code_block_caption_html(app, status, warning):
                '<span class="caption-number">Listing 1 </span>'
                '<span class="caption-text">caption <em>test</em> rb'
                '</span><a class="headerlink" href="#id1" '
-               'title="Permalink to this code">\xb6</a></div>')
+               'title="Link to this code">\xb6</a></div>')
     assert caption in html
 
 
@@ -443,7 +443,7 @@ def test_literalinclude_caption_html(app, status, warning):
                '<span class="caption-number">Listing 2 </span>'
                '<span class="caption-text">caption <strong>test</strong> py'
                '</span><a class="headerlink" href="#id2" '
-               'title="Permalink to this code">\xb6</a></div>')
+               'title="Link to this code">\xb6</a></div>')
     assert caption in html
 
 

tests/test_domain_c.py

@@ -1056,7 +1056,7 @@ def test_domain_c_c_maximum_signature_line_length_in_html(app, status, warning):
 </dl>
 
 <span class="sig-paren">)</span>\
-<a class="headerlink" href="#c.hello" title="Permalink to this definition">¶</a>\
+<a class="headerlink" href="#c.hello" title="Link to this definition">¶</a>\
 <br />\
 </dt>
 """

tests/test_domain_js.py

@@ -424,7 +424,7 @@ def test_domain_js_javascript_maximum_signature_line_length_in_html(app, status,
 </dl>
 
 <span class="sig-paren">)</span>\
-<a class="headerlink" href="#hello" title="Permalink to this definition">¶</a>\
+<a class="headerlink" href="#hello" title="Link to this definition">¶</a>\
 </dt>\
 """
     assert expected_parameter_list_hello in content
@@ -463,7 +463,7 @@ def test_domain_js_javascript_maximum_signature_line_length_in_html(app, status,
 {}{}{}{}{}{}</dl>
 
 <span class="sig-paren">)</span>\
-<a class="headerlink" href="#foo" title="Permalink to this definition">¶</a>\
+<a class="headerlink" href="#foo" title="Link to this definition">¶</a>\
 </dt>\
 """.format(expected_a, expected_b, expected_c, expected_d, expected_e, expected_f)
     assert expected_parameter_list_foo in content

tests/test_domain_py.py

@@ -1686,7 +1686,7 @@ def test_domain_py_python_maximum_signature_line_length_in_html(app, status, war
 <span class="sig-return-icon">&#x2192;</span> \
 <span class="sig-return-typehint"><span class="pre">str</span></span>\
 </span>\
-<a class="headerlink" href="#hello" title="Permalink to this definition">¶</a>\
+<a class="headerlink" href="#hello" title="Link to this definition">¶</a>\
 </dt>\
 """
     assert expected_parameter_list_hello in content
@@ -1725,7 +1725,7 @@ def test_domain_py_python_maximum_signature_line_length_in_html(app, status, war
 {}{}{}{}{}{}</dl>
 
 <span class="sig-paren">)</span>\
-<a class="headerlink" href="#foo" title="Permalink to this definition">¶</a>\
+<a class="headerlink" href="#foo" title="Link to this definition">¶</a>\
 </dt>\
 """.format(expected_a, expected_b, expected_c, expected_d, expected_e, expected_f)
     assert expected_parameter_list_foo in content

tests/test_ext_inheritance_diagram.py

@@ -170,7 +170,7 @@ def test_inheritance_diagram_png_html(tmp_path, app):
                '<img src="_images/inheritance-\\w+.png" alt="Inheritance diagram of test.Foo" '
                'class="inheritance graphviz" /></div>\n<figcaption>\n<p>'
                '<span class="caption-text">Test Foo!</span><a class="headerlink" href="#id1" '
-               'title="Permalink to this image">\xb6</a></p>\n</figcaption>\n</figure>\n')
+               'title="Link to this image">\xb6</a></p>\n</figcaption>\n</figure>\n')
     assert re.search(pattern, content, re.M)
 
     subdir_content = (app.outdir / 'subdir/index.html').read_text(encoding='utf8')
@@ -219,7 +219,7 @@ def test_inheritance_diagram_svg_html(tmp_path, app):
                '<p class=\"warning\">Inheritance diagram of test.Foo</p>'
                '</object></div>\n<figcaption>\n<p><span class="caption-text">'
                'Test Foo!</span><a class="headerlink" href="#id1" '
-               'title="Permalink to this image">\xb6</a></p>\n</figcaption>\n</figure>\n')
+               'title="Link to this image">\xb6</a></p>\n</figcaption>\n</figure>\n')
 
     assert re.search(pattern, content, re.M)
 
@@ -280,7 +280,7 @@ def test_inheritance_diagram_latex_alias(app, status, warning):
                '<img src="_images/inheritance-\\w+.png" alt="Inheritance diagram of test.Foo" '
                'class="inheritance graphviz" /></div>\n<figcaption>\n<p>'
                '<span class="caption-text">Test Foo!</span><a class="headerlink" href="#id1" '
-               'title="Permalink to this image">\xb6</a></p>\n</figcaption>\n</figure>\n')
+               'title="Link to this image">\xb6</a></p>\n</figcaption>\n</figure>\n')
     assert re.search(pattern, content, re.M)
 
 

tests/test_markup.py

@@ -383,9 +383,9 @@ def get(name):
         '.. glossary::\n\n   term1\n   term2\n       description',
         ('<dl class="simple glossary">\n'
          '<dt id="term-term1">term1<a class="headerlink" href="#term-term1"'
-         ' title="Permalink to this term">¶</a></dt>'
+         ' title="Link to this term">¶</a></dt>'
          '<dt id="term-term2">term2<a class="headerlink" href="#term-term2"'
-         ' title="Permalink to this term">¶</a></dt>'
+         ' title="Link to this term">¶</a></dt>'
          '<dd><p>description</p>\n</dd>\n</dl>'),
         None,
     ),