Allow to bail out extlink replacement suggestion

[gaborbernat]

Feature added via #9800. Consider the following ext link:

# conf.py
extlinks = {
    "user": ("https://github.com/%s", "@"),
}

and the following text:

All pull requests and merges to the ``main`` branch are tested using `GitHub Actions <https://github.com/features/actions>`_ .

hardcoded link 'https://github.com/features/actions' could be replaced by an extlink (try using ':user:`features/actions`' instead)

Can we somehow bailout out the check here, or perhaps the suggestion should only apply if there's no / in the extlink, @tk0miya what do you think? cc @hoefling

[ssbarnea]

This affected me too on other project and what I find it quite problematic for two reasons:

• it seems that this feature does not work on macos, I get this warning only on linux --- weird
• i do not see any option to silence it and because I use strict mode, it broke the CI
• people may want to avoid using sphinx specific constructs in order to keep the file editable and rendable by more tools

The only workaround that I see now is to pin-down sphinx to <4.4.0.

[tk0miya]

I agree it's needed to control the check feature (#10113 is a related story). I'm not sure it's really needed to control the check by file or individual URL. So I'd like to add an option to enable/disable the checks for the whole of the project.

[gaborbernat]

I'm not sure it's really needed to control the check by file or individual URL.

I for one like this feature for all my sphinx only files, but then there's an index file used by pypi.org where a file-level exclude list would be helpful. The individual URL disable would be there to bypass bugs of detection without needing to turn off the feature entirely.

[tk0miya]

it seems that this feature does not work on macos, I get this warning only on linux --- weird

IMO, this feature is not related to the OS. So I'm not sure why it does not work on macOS. How about call make clean before building?

people may want to avoid using sphinx specific constructs in order to keep the file editable and rendable by more tools

Understandable. The PyPI's case is one of them.

[tk0miya]

The individual URL disable would be there to bypass bugs of detection without needing to turn off the feature entirely.

Please let me know what case do you want to disable the check? I can understand the PyPI's case. But another one is not yet.

[gaborbernat]

Please let me know what case do you want to disable the check? I can understand the PyPI's case. But another one is not yet.

See my first post here #10112 (comment) with the github actions link being suggested as a user link.

[hoefling]

I'm actually fine with reverting #9800 completely. While issuing the warnings actually makes sense for every hardcoded link that can be replaced with intersphinx (as suggested in #9626), it's just not worth it with extlinks since it now forces to use the roles even for unrelated URLs. In the example listed by @gaborbernat, it would mean

extlinks = {
    "user": ("https://github.com/%s", "@"),
    "feature": ("https://github.com/%s", "feat"),
}

and rewriting the link to :feat:`GitHub Actions <actions>`, and it's just too much fuzz for a single link.

[gaborbernat]

Hence why I was proposing that the suggestion should only apply if there's no / in the part represented by %s. I think that'd fix 99% of the cases here.

[tk0miya]

I think extlinks can accept shortcuts contains /. For example, :repo:`sphinx-doc/sphinx` should be allowed. So -1 for the rule.

[gaborbernat]

Be that so, but I don't think your commit solves this issue. Adding a global disable flag is not what this issue is about. I purposefully formulated it to keep the feature but allow disabling it where the check makes invalid suggestions 🤔

[tk0miya]

Indeed. My PR and your trouble are different topics. So the title of the PR is not good.

[acolomb]

I think extlinks can accept shortcuts contains /. For example, :repo:`sphinx-doc/sphinx` should be allowed. So -1 for the rule.

I'd also like to keep the possibility of using / in the replacement string. Example: :pull:`1234/files` for directly linking to a PR's diff view. Noticed this while working on https://github.com/syncthing/docs. Glad to see activity on a quick fix in #10126.

[asottile]

I don't think github is special here -- the same could be said for any other vcs, or really any other popular website. I do think that the heuristic of "contains a slash" is a pretty good approximation for disabling the warning (that would solve 99% of the false positive warnings)

[mzjn]

Here is a workaround. Add the following lines to conf.py to suppress the warnings:

from sphinx.util import logging

linklogger = logging.getLogger('sphinx.ext.extlinks')
linklogger.setLevel(40) # Ignore messages less severe than ERROR

[tk0miya]

I don't think github is special here -- the same could be said for any other vcs, or really any other popular website.

Are you saying all case of extlink usage does not contain a slash or it's a special case? If so, we should mention the restrictions on the document of extlink. But I'm not sure the rule is a standard rule...

[asottile]

no, you're not understanding me or gaborbernat

we are merely suggesting that the WARNING should not fire if the replacement contains a slash

that would eliminate the frustration with the new warning which has a very high false positive rate in its current implementation

we are not talking about disallowing slashes in extlinks or changing how extlinks work at all -- merely the warning

#10137 implements that and contains a test demonstrating this behaviour

[tk0miya]

Really? The recommendation logic you proposed will never warn for references containing a slash. It means it does not consider URLs containing a slash are not candidates of extlink, right?

that would eliminate the frustration with the new warning which has a very high false positive rate in its current implementation

I understand the current implementation is very noisy for some people. So I thought disable it by default via #10126, and improve the logic in the next step.

If you're proposing #10137 as a workaround, I can understand. But the current implementation causes other troubles. So I'd like to disable it by default.

[asottile]

again, I'm not proposing to change how extlinks works -- just eliminating the warning in a common case

extlinks would still support slashes in replacements -- but from some searching on sourcegraph this feature seems to be scarcely or never used (I could not find an example in any projects from my search -- though I only scrolled through projects 5k stars and above)

the search I used:

:[^:\n]+:`[^`\n]+/[^`\n]+` file:\.rst$

so my proposal would leave the warning on (since I think the warning is useful -- it certainly helped me find a mistake in flake8) but it would eliminate a high false positive case that's almost always not intended to use extlinks

[Cielquan]

I like the proposal from @gaborbernat and @asottile as this would silence most of the false positives for me too. But I still have an issue which would be better solved by a file exclusion list.

In the config.py I have extlinks={"repo": "https://github.com/user/some_repo/%s"}.
I include the CHANGELOG.md file from the repo's root in the docs. In the changelog I have a link to the releases page https://github.com/user/some_repo/releases and also compare links for each release like https://github.com/user/some_repo/compare/v1.0.0...main.

With the proposal the compare links would be silent, but the release link would still fire a warning. I do not want to replace any link in the changelog, because it should also be usable outside of the docs context.

[jodygarnett]

Just want to make a note that these warnings are unavoidable when mixing RST (documentation) and MarkDown (release notes) in a project.

  * Fix: [GEOS-10282](https://osgeo-org.atlassian.net/browse/GEOS-10282)

The markdown release notes generate this warning on extlink replacement:

WARNING: hardcoded link 'https://osgeo-org.atlassian.net/browse/GEOS-10282' could be replaced by an extlink (try using ':geos:`10282`' instead)

This is a shame as I enjoyed being able to cut and paste markdown out of issue tracker.

[kmuehlbauer]

We have the same issue while pulling in .rst documents from project-root via include-directive.

As the included .rst should just render fine outside sphinx compiled docs, the recommended change emitted by the WARNING is just not usable for us. As @Cielquan pointed out a file-exclusion list would help to solve this for us.

[ssbarnea]

Maybe I am missing something but seeing that no1 regression I observed as being introduced by Sphinx 4.4.0, not only as not being fixed in 4.4.1 or 4.5.0, but postponed for 5.0.0.

That is something that will make people stick with older and older sphinx and avoid upgrading it.

[lethosor]

I'm no longer seeing the warning in Sphinx 4.5.0, and there is a mention of a change in the 4.5.0 changelog. So that part appears to have been resolved. I assume the issue remains open to track more complex future configuration support.