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

Backtick-quoted links with no explicit target in rule documentation #16010

Open
InSyncWithFoo opened this issue Feb 7, 2025 · 1 comment
Open
Labels
documentation Improvements or additions to documentation help wanted Contributions especially welcome

Comments

@InSyncWithFoo
Copy link
Contributor

InSyncWithFoo commented Feb 7, 2025

FAST002's rule documentation reads:

The [FastAPI documentation] recommends the use of [`typing.Annotated`] for
<!-- ... -->
[fastAPI documentation]: https://fastapi.tiangolo.com/tutorial/query-params-str-validations/?h=annotated#advantages-of-annotated
[typing.Annotated]: https://docs.python.org/3/library/typing.html#typing.Annotated

This is how PyCharm renders it:

And GitHub:

The FastAPI documentation recommends the use of [typing.Annotated] for

CommonMark dingus is no different:

<p>The <a href="https://fastapi.tiangolo.com/tutorial/query-params-str-validations/?h=annotated#advantages-of-annotated">FastAPI documentation</a> recommends the use of [<code>typing.Annotated</code>] for</p>

Links of the form [`something`] is not very well-recognized by renderers and thus should be avoided, similar to the "automatic" option links discussed in #14348.


The easiest way to fix them would be to use an explicit target:

The [FastAPI documentation] recommends the use of [`typing.Annotated`][typing-annotated] for
<!-- ... -->
[fastAPI documentation]: https://fastapi.tiangolo.com/tutorial/query-params-str-validations/?h=annotated#advantages-of-annotated
[typing-annotated]: https://docs.python.org/3/library/typing.html#typing.Annotated

GitHub handles this much better:

The FastAPI documentation recommends the use of typing.Annotated for

And so does CommonMark dingus:

<p>The <a href="https://fastapi.tiangolo.com/tutorial/query-params-str-validations/?h=annotated#advantages-of-annotated">FastAPI documentation</a> recommends the use of <a href="https://docs.python.org/3/library/typing.html#typing.Annotated"><code>typing.Annotated</code></a> for</p>
@InSyncWithFoo InSyncWithFoo changed the title Backtick-quoted no-URI links in rule documentation Backtick-quoted links with no explicit target in rule documentation Feb 7, 2025
@ntBre ntBre added the documentation Improvements or additions to documentation label Feb 7, 2025
@MichaReiser MichaReiser added the help wanted Contributions especially welcome label Feb 7, 2025
@InSyncWithFoo
Copy link
Contributor Author

InSyncWithFoo commented Feb 7, 2025

\[`[^`]+`\](?![\[(]) returns 359 hits, while that of \[`(?!lint\.)[^`]+`\](?![\[(]) is 67. This shows that the vast majority of broken links are option pseudo-links (and even then, there are still line-length, target-version and other top-level options that haven't been filtered out).

Fixable links can be found using \[`([^`]+)`\](?![\[(])(?=.*+(?>\R///.*)*\R/// \[\1) (or \[`([^`]+)`\](?![\[(])(?=.*\\n\[\1\]:) if you prefer working with ruff rule --all --output-format=json).

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation Improvements or additions to documentation help wanted Contributions especially welcome
Projects
None yet
Development

No branches or pull requests

3 participants