search

matplotlib / matplotlib

matplotlib: plotting with Python
https://matplotlib.org/stable/
19.96k stars 7.56k forks source link

[Doc]: document "out-of-the-box" interactivity #28722

Open story645 opened 4 weeks ago

story645 commented 4 weeks ago

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:

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:

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:

Tutorials

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.

jklymak commented 4 weeks ago

I was told to discuss docs here. I can't parse most of what is being said above, however at https://github.com/matplotlib/matplotlib/issues/28708 it was stated more succinctly that

I think adding one more section to that document so it's an even larger collection of related but disjoint topics would make that page even harder to maintain and the documentation even more undiscoverable

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

The reason for "everything gets its own page" is b/c I think tighter scoping

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 :+1: 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 commented 4 weeks ago

"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.

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:

But I think tearing it apart and starting from scratch is not a good plan. People learn much better from books than flashcards.

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:

In the table of contents it is under "User Guide->Figures->Interacting with Figures" which seems as reasonable a place as any.

"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.

he 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.

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.