René's URL Explorer Experiment

{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"[Doc]: document \"out-of-the-box\" interactivity","articleBody":"### Documentation Link\r\n\r\n_No response_\r\n\r\n### Problem\r\n\r\nSpun 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. \r\n\r\nWhat 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). \r\n\r\nOr take the [interactivity docs](https://matplotlib.org/devdocs/users/explain/figure/interactive.html), which have a structure of:\r\n* repl based live updating\r\n* GUI/UI options + keybindings\r\n* backends\r\n\r\nAnd the other \"interactivity docs\" are very desktop gui application oriented:\r\n* [how to event loop?](https://matplotlib.org/devdocs/users/explain/figure/interactive_guide.html)\r\n* [event handling/pickling](https://matplotlib.org/devdocs/users/explain/figure/event_handling.html)\r\n\r\nAnd some of the for free things are just undocumented or hard to find:\r\n*  #9593 which could be closed by #25187\r\n*  #5839\r\n* #19037\r\n\r\n### Suggested improvement\r\n\r\nMy proposal is half restructuring/half writing new docs:\r\n\r\n### User guide\r\nThe 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:\r\n- [ ] going w/ the current structure, pull all the interactivity/event handling docs into their own section/folder\r\n- [ ] use the \"index.html\" to roadmap folks to which part of the interactivity docs they want, which would close #19037\r\n- [ ] create a new \"out-of-the-box\" page that provides an overview of the just there w/ an interactive backend features:\r\n  - [ ] pan/zoom, sharex/sharey, draggable, cursors (closing #9593), color updates, etc\r\n- [ ] separate out [interactive.html](https://matplotlib.org/devdocs/users/explain/figure/interactive.html) into seperate pages for each topic:\r\n  - [ ] live updating in a repl\r\n  - [ ] gui navigation/toolbinding\r\n  - [ ] 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\r\n\r\n### Tutorials\r\n- [ ] add a tutorial showing how to:\r\n  - [ ] use the out of the box things to build a simple data viewer,  \r\n  - [ ] building on that, add a widgets interaction\r\n  - [ ] building on that, write something custom using the events system\r\n\r\nmy 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. \r\n\r\n### Examples\r\nHopefully just showing how the widgets are interactive will yield discoverability gains:\r\n* #23441 \r\n\r\nETA: 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. ","author":{"url":"https://github.com/story645","@type":"Person","name":"story645"},"datePublished":"2024-08-14T17:54:56.000Z","interactionStatistic":{"@type":"InteractionCounter","interactionType":"https://schema.org/CommentAction","userInteractionCount":2},"url":"https://github.com/28722/matplotlib/issues/28722"}