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

extlinks warnings: Improve suggestions when reST references are involved #10125

Closed
pradyunsg opened this issue Jan 21, 2022 · 2 comments
Closed
Labels
extensions type:proposal a feature suggestion
Milestone

Comments

@pradyunsg
Copy link
Contributor

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/6831
    

    The 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/pip
  • cd pip
  • pip install nox
  • nox -s docs
  • See error!

Expected behavior

No response

Your project

https://github.com/pypa/pip/

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

@pradyunsg
Copy link
Contributor Author

There wasn't any good spot to say this in the issue template: I appreciate the work that y'all do! ^.^

@tk0miya tk0miya added this to the 4.5.0 milestone Jan 22, 2022
@tk0miya tk0miya added type:proposal a feature suggestion and removed type:bug labels Jan 23, 2022
tk0miya added a commit that referenced this issue Jan 30, 2022
Close #10125: extlinks: Improve suggestion message for a reference having title
@pradyunsg
Copy link
Contributor Author

Thanks @tk0miya! ^>^

@github-actions github-actions bot locked as resolved and limited conversation to collaborators Mar 4, 2022
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Labels
extensions type:proposal a feature suggestion
Projects
None yet
Development

No branches or pull requests

2 participants