matplotlib / matplotlib/matplotlib

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

Open
#28,722 2 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Documentation
Dominant language
Python
Stars
23.2k
Forks
8.5k
Avg merge
1d 6h
Merged PRs (30d)
66

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](https://matplotlib.org/devdocs/search.html?q=sharex), with the interactivity a bullet point in [the pan/zoom overlap example](https://matplotlib.org/devdocs/gallery/showcase/pan_zoom_overlap.html).

Or take the [interactivity docs](https://matplotlib.org/devdocs/users/explain/figure/interactive.html), 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?](https://matplotlib.org/devdocs/users/explain/figure/interactive_guide.html)
* [event handling/pickling](https://matplotlib.org/devdocs/users/explain/figure/event_handling.html)

And some of the for free things are just undocumented or hard to find:
* #9593 which could be closed by #25187
* #5839
* #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 #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 #9593), color updates, etc
- [ ] separate out [interactive.html](https://matplotlib.org/devdocs/users/explain/figure/interactive.html) into seperate pages for each topic:
- [ ] live updating in a repl
- [ ] gui navigation/toolbinding
- [ ] move the backends discussion to [backends.html](https://matplotlib.org/devdocs/users/explain/figure/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:
* #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.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by reading the current interactive.html, interactive_guide.html, event_handling.html, backends.html, and the user-guide index. Compare those pages with the checklist for the out-of-the-box overview, restructuring, tutorials, and examples. Done means an agreed documentation plan is implemented and the listed interactive features are discoverable through the user guide.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
data-visualization, documentation
Issue type
Documentation
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
30/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.