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.

I'll ping about this. Adding reference labels to files has only a very mild cost to file size and makes changes robust to reorganization. Whether one uses :doc: or :ref: is sort of orthogonal, though I'd still advocate pretty strongly for :ref: due to its flexibility.

Independent of examples, my understanding of labels is that you define them just when you need to :ref: them. It feels premature to define labels just in case. We do not do this for sections. So if we say :ref:ing examples is ok, I'd follow that practice.

Other than that, I believe both our positions are clear and we need somebody else to take a stance.

For sure - these were all used in #29124.

I am weakly 3 > 2 > 1 . One practical difference is that the :doc: link hits the very top of the page, the :ref: link will be scrolled down a little bit so that the title is at the top of the browser window (which if you target the top heading effectively cuts off the cookie crumb bar).

I'm inclined to merge this.

One practical difference is that the :doc: link hits the very top of the page, the :ref: link will be scrolled down a little bit so that the title is at the top of the browser window (which if you target the top heading effectively cuts off the cookie crumb bar).

I find this very annoying, links to examples should go to the top of the page. Everything else looks like a bug and always makes me uneasy whether there is something hidden above (though technically I know there isn’t.

Independently, I still don’t see why we need to prematurely add all the labels. Even if you rather :ref: than :doc: you can add them as you need them.

This feels like unnecessary clutter to me.

I have the opposite sense in that I like that the :ref: links scroll down a bit to hide the boiler plate!

This is extracted from #29124 which does use them all so with that context this is not preemptive.

I still find the addition awkwardly ad-hoc. The labels don’t comply with our existing label conventions (no underscores) https://matplotlib.org/devdocs/devel/document.html#refer-to-other-documents-and-sections

Also, if we’re going to systematically use labels for examples, I recommend to extend the policy and prefix the example labels with example- (or similar). IMHO it would help to immediately see that categorical_variables references an example and not e.g. a technical explanation.

The labels don’t comply with our existing label conventions (no underscores)

Hmm, and I even wrote that convention - happy to fix all these to be dashes...

if we’re going to systematically use labels for examples, I recommend to extend the policy and prefix the example labels with example-

That seems reasonable - I'll try to add a prefix to these where it makes sense

The latest commit only does examples-trisurf3d for examples/mplot3d/trisurf3d.py so the label is not fully resolving the file hierarchy, but I think that should be enough...

I’m still not a big fan, but not enough to block if others think this is the way to go. So do as you see fit.