Context: There are two ways in which we can reference examples:

• :doc: links, e.g. :doc:`/gallery/lines_bars_and_markers/categorical_variables` where the role content is the file path
• :ref: links, e.g. :ref:`some_label` where the label name can be choosen freely

We currently have 150 :doc: links and 7 :ref: links mapping to examples.

I give my perspective on the advantages / disavantages of :ref: links vs. :doc: links to examples.

Advantage:

• it is possible to change the example filenames / directory structure without breaking the links

Disadvantage:

• giving examples labels is additional effort and slightly more clutter. Admittedly not much, but still a bit.
• we have to come up with dedicated names. What should that be? AFAICS proposed here is the file name. That's easy to do and remember. But we would loose this connection if we pull the advantage above and rename the files.
• I find it exteremely helpful that the link :doc:`/gallery/lines_bars_and_markers/categorical_variables` explicitly states it's a lines_bars_and_markers example. Whereas :ref:`categorical_variables` could basically to all kinds of docs. This is so much, that I'd strongly recommend to use some prefix in the label if we want to use labels, e.g. :ref:`example-categorical_variables`
• When developing and wanting to see which example is referenced I go to https://matplotlib.org/stable and paste the contents of the :doc: role behind. This directly gets me to the rendered example. Looking this up from the label is much more complicated.
• The :doc: link brings you to the top of the page (e.g. https://matplotlib.org/stable/gallery/color/named_colors.html), whereas the :ref: link brings to to the first section anchor (e.g. https://matplotlib.org/stable//gallery/color/named_colors.html#list-of-named-colors). I find top of the page slightly cleaner: the URL is shorter and the page is not yet scrolled down a little.

IMHO :ref: links for examples only have the advantage that we can change the filenames / directory structure without the need to update the links. But we rarely do that (i) because it's rarely needed and (ii) such a change requires putting up a redirect, which is some effort in itself. I don't see an additional search/replace for the corresponding :doc: would make much of a difference.

On the background that the examples references are much more read than changed I find that the disadvantages for reading/using outweigh the possibility of a slightly simpler filename/directory change. Therefore, I'm 0.5 on this.

First, the references to examples comparison is a bit chicken and egg - the example gallery was made without references, so no one refers to them. However :ref: is used 683 times in the code base, whereas :doc: is used 292 times, so in the past we have made extensive use of :ref:.

I think there are pros and cons to both referencing systems that depend a little on how you work - referencing by the webpage path is fragile and doesn't match the code tree path so its not very straightforward, and if you reference the stable docs, you need to remember what part of the path to refer to in the :doc: reference. Thats not very self contained, and I often find it simpler to find the source code and look at the reference at the top of the page.

Regardless, this PR isn't prescriptive is how anyone uses the references or not - it just adds the references.

However :ref: is used 683 times in the code base, whereas :doc: is used 292 times,

That's also apples to oranges. In written .rst docs, you often have multiple sections in a document and want to link to a specific section inside the document, not the document as a whole. It's reasonable (and for non-top-level sections a necessity) to use :ref: there. In contrast we want to reference examples as a whole, not the title of the example.

Regardless, this PR isn't prescriptive is how anyone uses the references or not - it just adds the references.

We shouldn't "just add" stuff. I value consistency very high and want an agreed upon and documented policy how we want to reference docs. That may seem pedantic but IMHO it would be the worst outcome if half of the examples are referenced by :doc: and the other half by :ref:. Currently we predominantly use :doc: for example references and also explicitly use a gallery example for a :doc: example it in our documentation guide. If you want to change this, I want to have this conversation. I'm fine if others vote in favor of always using :ref:, but please let's do this systematically and not create a mess.

That link takes me to a page that describes using both :doc: and :ref:, and so far as I can tell does not prescribe any rule as to when you should use which.

Also note that the document you link does explicitly advise against names like example-categorical_variables.

If you want to change this,

I don't think I am proposing to change anything. I am pretty sure I chose the original examples to reference with :doc: (#9884) and I certainly had no intention of claiming that was the only way to reference the pages I chose. I think you are over interpreting what is written there.

Ok, maybe I'm overinterpreting and we don't have a standardized approach for referencing examples. But then I'd like to clarify our policy here. We have three options for example references:

1. Always use :doc:
2. Always use :ref:
3. Don't set a rule and use a mixture of both.

My priority would be (1) > (2) > (3) for the reasons already given above.

What do you propose?

I think we should have lots of cross references. I don't really care what form they take, but given that ref works whether I am referencing page or a section, I have a mild preference for it. So I guess my ranking is 3>2>1.

Ok, now we have pinned the conflict 1>2>3 vs. 3>2>1. Should we move this to one of the next dev calls? I suspect it might be easier to find an agreement there rather than through a written discussion.