plotly / plotly/plotly.py

Better magic_underscore explanation in docstrings

Aperta
#1,925 2 commenti 0 reazioni 1 assegnatario Vedi su GitHub

@nicholas-esterer ci sta già lavorando.

Dal 13/10/2020.

documentation feature P3
Lingua principale
Python
Stelle
18.8k
Fork
2.8k
Merge medio
16h 26m
PR unite (30g)
21

Descrizione

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_objects that accept **kwargs should include an entry for this in the docstring.
  • Wherever we accept another graph_object (e.g. marker in go.Scatter) the docstring could mention that you can also to marker_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 arguement x in this function which accepts a graph_object, you may use x_y where y is a valid property of the corresponding graph_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 patch and kwargs that the relevant attributes are to be found in plotly.graph_objects.layout.Xaxis etc.

@emmanuelle thoughts?

Guida per i contributori

Apri la guida per i contributori

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Valutazione

Questa issue non è ancora stata valutata.

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.