Repository navigation
[Doc]: document "out-of-the-box" interactivity #28722
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.
Activity
jklymak commentedon Aug 15, 2024
I was told to discuss docs here. I can't parse most of what is being said above, however at #28708 it was stated more succinctly that
which I largely don't agree with - the page, https://matplotlib.org/stable/users/explain/figure/interactive.html, is the top hit for a google search on "Matplotlib interactivity" so it is very discoverable. In the table of contents it is under "User Guide->Figures->Interacting with Figures" which seems as reasonable a place as any.
"related but disjoint" is an oxymoron; I would write that page a bit differently, and I think it could be modernized, but it seems to flow pretty naturally - this is how you get a GUI, here is how you can interact with it.
"harder to maintain" - sections and subsections in a document don't strike me as hard to maintain.
Conversely
every paragraph or subsection getting its own page will be very hard to maintain; if I need to add a topic or modify a topic I need to first figure out if a page exists, read the possible relevant ones, and then either add a page or modify one or more of the existing ones. A single page with good subsections is a quick search/skim of the headings. I feel pretty strongly that the scope of the existing page is fine, and the number of topics in it is appropriate and both "discoverable" and "maintainable". People learn much better from books than flashcards.
I'm 👍 for improving https://matplotlib.org/stable/users/explain/figure/interactive.html maybe with some mild reorganization, and some salient additions would be great. But I think tearing it apart and starting from scratch is not a good plan.
story645 commentedon Aug 15, 2024
Related but disjoint is also how I'd describe the relationship between norms and colormapping -> the norms are used in colormapping, but they're also a standalone topic.
The page structure you propose isn't the current structure. The current structure is:
Why do you say that breaking concepts up into their own page w/ distinct purpose is making flashcards and not chapters in a book?
Again, my proposal was break things up in the following way:
"interacting with figures" is very broad and half that section is about backends. Which yes architecturally is deeply linked with interactivity, but generally from a "making visualizations" point of view interactivity is a distinct topic that focuses on the interactions:
ETA: I think that the current structure blends the what: interactivity with the how: backends/guis in a way that I think ends up making the what hard to find for folks who don't already know what the how is trying to achieve.
I'd probably repurpose that url as the landing page/overview of the whole interactivity section so wouldn't lose that. What I mean though is that page doesn't lead you to discover the 'out of the box" techniques or #19037 or widgets or many of the other nice things MPL offers for you to build your own interactive viz. Which is why I'd want to repurpose that page into an overview of what we offer for folks to build out viz.