Why was this example deleted? If you moved the docs to a class defn, fine, but leave the stub here with a link to the docs? Maybe w/ a small minimal example?

I didn't feel like it made sense to have the exact same example in two different places. My goal with these API docs was to be a strictly-better drop-in replacement for this example.

Is the concern here that the code that makes (what is now) theJoinStyle.demo figure is not as easily accessible in the docs anymore? I would propose that the example was not really adding much to the documentation via its code, but only really via its output (the visual representation of each Join/CapStyle is what's important).

Is the concern discoverability? I know that we have issues with Google sending people to old versions of the docs, but presumably the hope is that the new page quickly gets indexed as the go-to place for JoinStyle. In which case the relevant example figure will still be there.

If the concern is that people looking for that specific example will be confused as to where it went, then my impression of what's the best way to leave a "stub" behind is, instead of leaving an actual stub page with a link, we should really just use something likethe reredirects package to simply have an HTTP 301 response whenever someone tries to visit that page. As a side-effect this will also help with Google search indexing.

Something like the redirects package looks very interesting, though version 0.0.0 is a negative.

But the other concern is that the example will no longer will show up in the example gallery...

Haha fair, didn't realize the version number was so sketch, but frankly I can white room that package in a couple hours if we wanted to have our own implementation.

Gitlab reports that the whole "package" is only 62 lines of Python code. Was mostly linking it as a proof-of-principle that this is not impossible to do inside of Sphinx.

This may be totally off-base, but I struggle to imagine the user that scrolls through the examples gallery and is enticed to click on the JoinStyle demo in particular. Unless you know what it is already? But people that already know the name for something typically find examples by getting directly linked in via Google...

If I'm outvoted on that point, I guess we would just add two stub examples, one which just callsCapStyle.demo and one that callsJoinStyle.demo?

If you are browsing the examples, and come across it you learn something new. If you don't know what a join style is, you can never google it. People needsome way to know about the features in the library, and the example pages are basically it.

If you just want to have it call and link the class demo, thats perhaps fine. Then the plot shows up, and the user is linked to complete docs. But I think leaving it in as an example in the gallery is useful.

I think adding redirects is not the issue, but collating through the hundreds of old versions is a chore.

As for examples, I thought there was some talk of putting a smaller set of examples for all plot types, and maybe we could do the same for all these new style classes?

^ that would be great. However I don't think we should delete existing examples until that is created?

👍 for leaving stub examples and linking to the class. and later collecting these examples in a dedicated section.

(This is for discoverability rather than for keeping links alive).