matplotlib / matplotlib/matplotlib
[Doc]: document "out-of-the-box" interactivity
Chưa có ai nhận issue này.
- Ngôn ngữ chính
- Python
- Star
- 23.2k
- Fork
- 8.5k
- Merge trung bình
- 1 ngày 6 giờ
- Pull request đã merge (30 ngày)
- 66
Mô tả
### 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.
Hướng dẫn đóng góp
Bắt đầu từ đâu
- Đọc hết issue, rồi đọc hướng dẫn đóng góp của dự án.
- Bình luận trên issue rằng bạn sẽ nhận — tránh hai người làm cùng một việc.
- Fork repository và làm thay đổi trên một nhánh.
- Mở pull request có tham chiếu số hiệu của issue.
Hướng nghiên cứu
Bắt đầu bằng cách đọc các tệp hiện tại interactive.html, interactive_guide.html, event_handling.html, backends.html và mục lục của user-guide. So sánh các trang đó với checklist cho phần tổng quan có thể sử dụng ngay, việc tái cấu trúc, các hướng dẫn và các ví dụ. Công việc được xem là hoàn tất khi một kế hoạch tài liệu đã thống nhất được triển khai và các tính năng tương tác được liệt kê có thể được tìm thấy thông qua hướng dẫn sử dụng.
Do mô hình lập chỉ mục viết ra từ nội dung của issue.
Đánh giá
- Công nghệ
- python
- Lĩnh vực
- data-visualization, documentation
- Loại issue
- Tài liệu
- Độ khó
- 5/5
- Thời gian dự kiến
- Hơn một tuần
- Mức độ hoạt động
- Đình trệ
- Độ rõ ràng
- Cần làm rõ
- Mức phù hợp với người mới
- 30/100