matplotlib / matplotlib/matplotlib

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

Đang mở
#28,722 2 bình luận 0 reaction 0 người được giao Xem trên GitHub

Chưa có ai nhận issue này.

Documentation
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

Mở hướng dẫn đóng góp

Bắt đầu từ đâu

  1. Đọc hết issue, rồi đọc hướng dẫn đóng góp của dự án.
  2. 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.
  3. Fork repository và làm thay đổi trên một nhánh.
  4. 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

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.