plotly / plotly/plotly.py

Better magic_underscore explanation in docstrings

Offen
#1,925 2 Kommentare 0 Reaktionen 1 zugewiesene Person Auf GitHub ansehen

@nicholas-esterer arbeitet bereits daran.

Seit 13.10.2020.

documentation feature P3
Vorherrschende Sprache
Python
Sterne
18.8k
Forks
2.8k
Ø Merge
16 Std. 26 Min.
Gemergte PRs (30 T.)
21

Beschreibung

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?

Beitragsleitfaden

Beitragsleitfaden öffnen

Erste Schritte

  1. Lies das ganze Issue und danach den Beitragsleitfaden des Projekts.
  2. Schreib ins Issue, dass du es übernimmst — das erspart doppelte Arbeit.
  3. Forke das Repository und arbeite in einem Branch.
  4. Öffne einen Pull Request, der die Issue-Nummer nennt.

Bewertung

Dieses Issue wurde noch nicht bewertet.

Neue Issues direkt in Ihr Postfach

Eine kurze Übersicht über anfängerfreundliche GitHub-Issues.