extlinks warnings: Improve suggestions when reST references are involved #10125
Description
Describe the bug
The suggestions made in warnings by extlinks are incomplete, and not a drop-in replacement in most cases.
extlinks = {
"issue": ("https://github.com/pypa/pip/issues/%s", "#"),
"pull": ("https://github.com/pypa/pip/pull/%s", "PR #"),
"pypi": ("https://pypi.org/project/%s/", ""),
}
-
For:
`"Permission denied" error <https://github.com/pypa/pip/issues/8418>`__The warning presented is:
/Users/pradyunsg/Developer/pip/docs/html/cli/pip_freeze.rst:80: WARNING: hardcoded link 'https://github.com/pypa/pip/issues/8418' could be replaced by an extlink (try using ':issue:`8418`' instead)This suggestion is suboptimal, since the equivalent replacement would actually be:
:issue:`"Permission denied" error <8418>` -
For:
`tracking issue`_ .. _`tracking issue`: https://github.com/pypa/pip/issues/6831The warning presented is:
/Users/pradyunsg/Developer/pip/docs/html/development/architecture/anatomy.rst:3: WARNING: hardcoded link 'https://github.com/pypa/pip/issues/6831' could be replaced by an extlink (try using ':issue:`6831`' instead)This suggestion is awkward, since there's no obvious way to make a drop-in replacement. Further, the line pointed to isn't the line with the actual URL to replace. Further, in case of multiple references to the same
tracking issue, there's no way to use extlinks without duplicating the issue number in multiple places.
How to Reproduce
(with a clean venv)
git clone https://github.com/pypa/pipcd pippip install noxnox -s docs- See error!
Expected behavior
No response
Your project
Screenshots
No response
OS
N/A
Python version
N/A
Sphinx version
4.4.0
Sphinx extensions
sphinx.ext.extlinks
Extra tools
No response
Additional context
No response