Fix reference definition labels for backtick-quoted shortcut links

[InSyncWithFoo]

Summary

Resolves #16010.

The changes boil down to something like this:

-/// The [FastAPI documentation] recommends the use of [`typing.Annotated`]
+/// The [FastAPI documentation] recommends the use of [`typing.Annotated`][typing-annotated]

-/// [typing.Annotated]: https://docs.python.org/3/library/typing.html#typing.Annotated
+/// [typing-annotated]: https://docs.python.org/3/library/typing.html#typing.Annotated

Test Plan

Mkdocs:

GitHub:

Why is this bad?

The FastAPI documentation recommends the use of typing.Annotated

...

CommonMark dingus:

<h2>Why is this bad?</h2>
<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></p>
<p>...</p>

[InSyncWithFoo]

That Mkdocs recognizes links like [`typing.Annotated`] in the first place is probably because it uses @Python-Markdown/markdown, an implementation of the original Markdown rather than CommonMark or GFM.

---

I think that's all of them. More importantly, there should be a test somewhere so that such a link can't possibly be accidentally introduced again. Where would I even put that?

[github-actions]

ruff-ecosystem results

Linter (stable)

✅ ecosystem check detected no linter changes.

Linter (preview)

✅ ecosystem check detected no linter changes.

[Daverball]

I think that's all of them. More importantly, there should be a test somewhere so that such a link can't possibly be accidentally introduced again. Where would I even put that?

Possibly here? https://github.com/astral-sh/ruff/blob/main/scripts/check_docs_formatted.py

That's where all of the other custom docs checks appear to happen. Although the main purpose appears to be ensuring that the examples are formatted correctly, there are a couple of unrelated checks as well, like ensuring the required sections for rule docs are present.

[InSyncWithFoo]

Possibly here? https://github.com/astral-sh/ruff/blob/main/scripts/check_docs_formatted.py

Section headers and code blocks are easy to check for, but inline links aren't. I imagine that would take quite some manual parsing/regexes on top of a list of every option known to Ruff.

[MichaReiser]

Would you mind updating your test plan and showing the rendered documentation for a page before/after your change (doesn't have to be for all of them, just pick one ;))

[MichaReiser]

It would be great if we'd have some linting or at least, guidance in the contribution guidelines. I otherwise worry, that we'll introduce incompatible links in the future. But that's something we can do separately.

Thank you!