Description
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:
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:
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.