Better magic_underscore explanation in docstrings
Đang mở
@nicholas-esterer đang làm issue này rồi.
Từ ngày 13/10/2020.
documentation
feature
P3
- Ngôn ngữ chính
- Python
- Star
- 18.8k
- Fork
- 2.8k
- Merge trung bình
- 16 giờ 26 phút
- Pull request đã merge (30 ngày)
- 21
Mô tả
I'd love to have a better answer for this kind of thing: https://stackoverflow.com/questions/58990657/python-how-do-i-find-inspect-what-kind-of-arguments-a-function-accepts
Some thoughts:
- The constructors of all the
graph_objectsthat accept**kwargsshould include an entry for this in the docstring. - Wherever we accept another graph_object (e.g.
markeringo.Scatter) the docstring could mention that you can also tomarker_whatever? - Wherever we accept
**kwargs, the docstring for that item should contain some self-contained explanation of what magic-underscores are and a link to the relevant docs. Minimally something like "for any other arguementxin this function which accepts agraph_object, you may usex_ywhereyis a valid property of the correspondinggraph_object." - For generic methods like update/add etc we should mention the name of the relevant graph_object whose properties are accepted, so that they show up in the Sphinx doc and provide a trail that users can follow. E.g. in https://plot.ly/python-api-reference/generated/plotly.graph_objects.Figure.html#plotly.graph_objects.Figure.update_xaxes we should mention in
patchandkwargsthat the relevant attributes are to be found inplotly.graph_objects.layout.Xaxisetc.
@emmanuelle thoughts?
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.
Đánh giá
Issue này chưa được đánh giá.