matplotlib / matplotlib/matplotlib
[Doc]: document "out-of-the-box" interactivity
Personne n'a encore pris cette issue.
- Langage dominant
- Python
- Étoiles
- 23.2k
- Forks
- 8.5k
- Merge moyen
- 1 j 6 h
- PR mergées (30 j)
- 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.
Guide de contribution
Ouvrir le guide de contribution
Par où commencer
- Lisez l'issue en entier, puis le guide de contribution du projet.
- Signalez en commentaire que vous la prenez — cela évite que deux personnes fassent le même travail.
- Forkez le dépôt et travaillez sur une branche.
- Ouvrez une pull request qui référence le numéro de l'issue.
Piste de recherche
Commencez par lire les fichiers actuels interactive.html, interactive_guide.html, event_handling.html, backends.html et l’index de user-guide. Comparez ces pages à la liste de contrôle pour la vue d’ensemble prête à l’emploi, la restructuration, les tutoriels et les exemples. La tâche est considérée comme terminée lorsqu’un plan de documentation convenu est mis en œuvre et que les fonctionnalités interactives listées sont accessibles depuis le guide utilisateur.
Rédigé par le modèle d'indexation à partir du texte de l'issue.
Évaluation
- Stack technique
- python
- Domaine
- data-visualization, documentation
- Type d'issue
- Documentation
- Difficulté
- 5/5
- Temps estimé
- Plus d'une semaine
- Activité
- À l'abandon
- Clarté
- À clarifier
- Accessibilité débutants
- 30/100