Skip to content

Commit

Permalink
extlinks: Disable hardcoded links detector by default (refs: #10126)
Browse files Browse the repository at this point in the history
The hardcoded links detector added since 4.4.0 causes troubles in many
projects.  Therefore, this disables it by default, and adds a new
configuration `extlinks_detect_hardcoded_links` to enable it explicitly.
  • Loading branch information
tk0miya committed Mar 27, 2022
1 parent a067946 commit c6230dc
Show file tree
Hide file tree
Showing 6 changed files with 26 additions and 0 deletions.
4 changes: 4 additions & 0 deletions CHANGES
Expand Up @@ -7,6 +7,8 @@ Dependencies
Incompatible changes
--------------------

* #10112: extlinks: Disable hardcoded links detector by default

Deprecated
----------

Expand All @@ -18,6 +20,8 @@ Features added
* #10260: Enable ``FORCE_COLOR`` and ``NO_COLOR`` for terminal colouring
* #10234: autosummary: Add "autosummary" CSS class to summary tables
* #10125: extlinks: Improve suggestion message for a reference having title
* #10112: extlinks: Add :confval:`extlinks_detect_hardcoded_links` to enable
hardcoded links detector feature
* #9494, #9456: html search: Add a config variable
:confval:`html_show_search_summary` to enable/disable the search summaries
* #9337: HTML theme, add option ``enable_search_shortcuts`` that enables :kbd:'/' as
Expand Down
8 changes: 8 additions & 0 deletions doc/usage/extensions/extlinks.rst
Expand Up @@ -59,3 +59,11 @@ The extension adds a config value:

Since links are generated from the role in the reading stage, they appear as
ordinary links to e.g. the ``linkcheck`` builder.

.. confval:: extlinks_detect_hardcoded_links

If enabled, extlinks emits a warning if a hardcoded link is replaceable
by an extlink, and suggests a replacement via warning. It defaults to
``False``.

.. versionadded:: 4.5
5 changes: 5 additions & 0 deletions sphinx/ext/extlinks.py
Expand Up @@ -47,6 +47,9 @@ class ExternalLinksChecker(SphinxPostTransform):
default_priority = 500

def run(self, **kwargs: Any) -> None:
if not self.config.extlinks_detect_hardcoded_links:
return

for refnode in self.document.findall(nodes.reference):
self.check_uri(refnode)

Expand Down Expand Up @@ -121,6 +124,8 @@ def setup_link_roles(app: Sphinx) -> None:

def setup(app: Sphinx) -> Dict[str, Any]:
app.add_config_value('extlinks', {}, 'env')
app.add_config_value('extlinks_detect_hardcoded_links', False, 'env')

app.connect('builder-inited', setup_link_roles)
app.add_post_transform(ExternalLinksChecker)
return {'version': sphinx.__display_version__, 'parallel_read_safe': True}
Expand Up @@ -3,3 +3,4 @@
'user': ('https://github.com/%s', '@%s'),
'repo': ('https://github.com/%s', 'project %s'),
}
extlinks_detect_hardcoded_links = True
1 change: 1 addition & 0 deletions tests/roots/test-ext-extlinks-hardcoded-urls/conf.py
@@ -1,2 +1,3 @@
extensions = ['sphinx.ext.extlinks']
extlinks = {'issue': ('https://github.com/sphinx-doc/sphinx/issues/%s', 'issue %s')}
extlinks_detect_hardcoded_links = True
7 changes: 7 additions & 0 deletions tests/test_ext_extlinks.py
@@ -1,6 +1,13 @@
import pytest


@pytest.mark.sphinx('html', testroot='ext-extlinks-hardcoded-urls',
confoverrides={'extlinks_detect_hardcoded_links': False})
def test_extlinks_detect_candidates(app, warning):
app.build()
assert warning.getvalue() == ''


@pytest.mark.sphinx('html', testroot='ext-extlinks-hardcoded-urls')
def test_replaceable_uris_emit_extlinks_warnings(app, warning):
app.build()
Expand Down

0 comments on commit c6230dc

Please sign in to comment.