Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Proposal: check if hardcoded URLs can be replaced with extlinks #9800

Merged
merged 4 commits into from Nov 29, 2021

Conversation

hoefling
Copy link
Contributor

Subject: This PR adds checks for hardcoded URLs whether they can be replaced with an extlink. This is a feature similar to #9626, but for extlinks instead of intersphinx.

Feature or Bugfix

  • Feature

Purpose

If a hardcoded link can be replaced with a crossref, sphinx will emit a warning like this:

pytest/doc/en/reference/reference.rst:127: WARNING: hardcoded link 'https://github.com/octocat' could be replaced by an extlink (try using ':user:`octocat`' instead)

Example output from running over Sphinx repository

/home/oleg.hoefling/projects/private/sphinx/doc/tutorial/narrative-documentation.rst:92: WARNING: hardcoded link 'https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#hyperlink-targets' could be replaced by an extlink (try using ':duref:`hyperlink-targets`' instead)

Relates

@hoefling hoefling changed the base branch from 4.x to master October 30, 2021 16:05
Copy link
Member

@tk0miya tk0miya left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM with nits.

We treat each ``reference`` node without ``internal`` attribute as an external link.
"""

default_priority = 900
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is there any reason for this priority? It's invoked on a very late step.
https://www.sphinx-doc.org/en/master/extdev/appapi.html#sphinx.application.Sphinx.add_transform

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

IMO, there is no special reason to invoke this feature earlier or later. So it would be better to put it on the normal priority: 500. I'll modify it after merging.

sphinx/ext/extlinks.py Outdated Show resolved Hide resolved
sphinx/ext/extlinks.py Outdated Show resolved Hide resolved
sphinx/ext/extlinks.py Outdated Show resolved Hide resolved
CHANGES Show resolved Hide resolved
@tk0miya tk0miya added this to the 4.4.0 milestone Nov 11, 2021
Signed-off-by: oleg.hoefling <oleg.hoefling@gmail.com>
Signed-off-by: oleg.hoefling <oleg.hoefling@gmail.com>
Signed-off-by: oleg.hoefling <oleg.hoefling@gmail.com>
Signed-off-by: Oleg Hoefling <oleg.hoefling@gmail.com>
@hoefling hoefling changed the base branch from master to 4.x November 12, 2021 08:57
@hoefling
Copy link
Contributor Author

@tk0miya thank you, those are very helpful! In fact, I'll apply those to #9626 as well.

hoefling added a commit to hoefling/sphinx that referenced this pull request Nov 12, 2021
Signed-off-by: oleg.hoefling <oleg.hoefling@gmail.com>
hoefling added a commit to hoefling/sphinx that referenced this pull request Nov 12, 2021
Signed-off-by: oleg.hoefling <oleg.hoefling@gmail.com>
@tk0miya tk0miya merged commit 74d9121 into sphinx-doc:4.x Nov 29, 2021
@tk0miya
Copy link
Member

tk0miya commented Nov 29, 2021

Thank you for update. Merging now.

tk0miya added a commit to tk0miya/sphinx that referenced this pull request Nov 29, 2021
tk0miya added a commit to tk0miya/sphinx that referenced this pull request Nov 29, 2021
tk0miya added a commit that referenced this pull request Nov 29, 2021
tk0miya added a commit to tk0miya/sphinx that referenced this pull request Nov 29, 2021
tk0miya added a commit that referenced this pull request Nov 29, 2021
hoefling added a commit to hoefling/sphinx that referenced this pull request Dec 9, 2021
Signed-off-by: oleg.hoefling <oleg.hoefling@gmail.com>
hoefling added a commit to hoefling/sphinx that referenced this pull request Dec 11, 2021
Signed-off-by: oleg.hoefling <oleg.hoefling@gmail.com>
hoefling added a commit to hoefling/sphinx that referenced this pull request Dec 20, 2021
Signed-off-by: oleg.hoefling <oleg.hoefling@gmail.com>
@github-actions github-actions bot locked as resolved and limited conversation to collaborators Dec 30, 2021
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

2 participants