In the dataclass() docs, every instance of dataclass() is a link, but to the very section I’m already reading. This seems unhelpful and distracting. Do people agree?
Also, “special methods” is linked but without the trailing s: special methods. This is because it’s to the glossary entry for “special method”. This seems overly pedantic. The link should be on the entire word, yes?
Yes to both.
There’s no need to link to itself, we can disable those with the ! prefix.
And we can use something like this to get a link like special methods:
-:term:`special method`s
+:term:`special methods <special method>
I would have simply removed the “:func:`dataclass`” markup, but I guess the ! prefix keeps the typographic style but suppresses the link?
Now I’m wondering if someone with Sphinx internals super-powers could write a linter of sorts to detect when a link is redundantly headed to its own section. Probably there are too many edge cases and ambiguities (what is the “same section”?)
Kinda like how Wikipedia works? A link to the current page is rendered in bolt instead of as a link? That’d be useful.
IMO whatever’s simplest, eg “the most recent heading” or “all heading levels moving up the tree”. Either of those would be fine, as would probably any other simple rule.
As Hugo mentioned, after discussion we all agreed that it was redundant and potentially confusing to link things to themselves, and the simplest way to disable the link (and also preserve the markup) is to just add ! in front of it.
I’ve mucked around with this like this and it should be possible to do as a doctree transform, but it would likely be kinda tricky and annoying as there are lots of different ref types (and each domain has differences in how xref resolution is implemented) and many cases to handle with many layers of nested nodes (as I see this more commonly with functions, classes, etc. vs section refs). However, if we do implement it, it would be comparatively trivial to just make it automatically disable link resolution and add a special class (that could be used in CSS to style such specially, like on Wikipedia as Chris mentions), rather than just issuing a warning and making the user fix it themself.
Just to note, this is invalid syntax; it would need to be :term:`special method`\s.
