Documentation Link

No response

Problem

Spun off from the discussion in #28708, the 'for free' interactivity Matplotlib provides - like the sharex/sharey brush linking or the colorbar/color updating or the data cursor - is not documented in an easily discoverable way.

What I mean is, for example sharex/sharey is mostly documented as a way to have the same ticks, with the interactivity a bullet point in the pan/zoom overlap example.

Or take the interactivity docs, which have a structure of:

• repl based live updating
• GUI/UI options + keybindings
• backends

And the other "interactivity docs" are very desktop gui application oriented:

• how to event loop?
• event handling/pickling

And some of the for free things are just undocumented or hard to find:

• DOC: need discoverable documentation for Axes.fmt_xdata #9593 which could be closed by DOC: document fmt_xdata, fmt_ydata, and fmt_zdata #25187
• Draggable annotations: documentation and bugreport #5839
• event loop and event handling docs are hard to find #19037

Suggested improvement

My proposal is half restructuring/half writing new docs:

User guide

The reason for "everything gets its own page" is b/c I think tighter scoping helps in identifying what docs go on which page, which helps with discoverability and maintainability:

• going w/ the current structure, pull all the interactivity/event handling docs into their own section/folder
• use the "index.html" to roadmap folks to which part of the interactivity docs they want, which would close event loop and event handling docs are hard to find #19037
• create a new "out-of-the-box" page that provides an overview of the just there w/ an interactive backend features:
  • pan/zoom, sharex/sharey, draggable, cursors (closing DOC: need discoverable documentation for Axes.fmt_xdata #9593), color updates, etc
• separate out interactive.html into seperate pages for each topic:
  • live updating in a repl
  • gui navigation/toolbinding
  • move the backends discussion to backends.html and link out to it in the sections that need this info - like the out of the box overview

Tutorials

• add a tutorial showing how to:
  • use the out of the box things to build a simple data viewer,
  • building on that, add a widgets interaction
  • building on that, write something custom using the events system

my plan was rework https://github.com/story645/pydata_nyc_2023 into an interactive GUI agnostic tutorial, but like perfectly cool w/ an alternative so long as it has a similar scaffolded structure b/c this structure covers all the things Matplotlib offers, but in a building on top of previous way.

Examples

Hopefully just showing how the widgets are interactive will yield discoverability gains:

• Add mpl-playback to widgets gallery examples #23441

ETA: I'm willing to do some/most/all of this work myself (or mentor folks/champion PRs) iff we get to some rough consensus on a plan.