IntenseWebs/sphinx
3
0
Fork 0
mirror of https://github.com/sphinx-doc/sphinx.git synced 2025-02-25 18:55:22 -06:00
Code Issues Packages Projects Releases Wiki Activity

Be more ephemeral (in anchor link title text)

Browse Source
This commit is contained in:
Adam Turner
2023-08-12 05:21:16 +01:00
parent 0e2ba0a1e4
commit 7e9a2066c2
12 changed files with 36 additions and 34 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
CHANGES
View File

@@ -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
-------

8
doc/usage/configuration.rst
View File

@@ -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

2
sphinx/ext/imgmath.py
View File

@@ -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:

2
sphinx/ext/mathjax.py
View File

@@ -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()]

25
sphinx/writers/html5.py
View File

@@ -96,7 +96,7 @@ class HTML5Translator(SphinxTranslator, BaseTranslator):
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 @@ class HTML5Translator(SphinxTranslator, BaseTranslator):
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 @@ class HTML5Translator(SphinxTranslator, BaseTranslator):
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 @@ class HTML5Translator(SphinxTranslator, BaseTranslator):
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 @@ class HTML5Translator(SphinxTranslator, BaseTranslator):
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 @@ class HTML5Translator(SphinxTranslator, BaseTranslator):
# 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')

8
tests/test_build_html.py
View File

@@ -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')

4
tests/test_directive_code.py
View File

@@ -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

2
tests/test_domain_c.py
View File

@@ -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>
"""

4
tests/test_domain_js.py
View File

@@ -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

4
tests/test_domain_py.py
View File

@@ -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

6
tests/test_ext_inheritance_diagram.py
View File

@@ -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)

4
tests/test_markup.py
View File

@@ -383,9 +383,9 @@ def get_verifier(verify, verify_re):
'.. 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,
),