plotly / plotly/plotly.py

Better magic_underscore explanation in docstrings

Ouverte
#1,925 2 commentaires 0 réactions 1 personne assignée Voir sur GitHub

@nicholas-esterer y travaille déjà.

Depuis le 13/10/2020.

documentation feature P3
Langage dominant
Python
Étoiles
18.8k
Forks
2.8k
Merge moyen
16 h 26 min
PR mergées (30 j)
21

Description

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?

Guide de contribution

Ouvrir le guide de contribution

Par où commencer

  1. Lisez l'issue en entier, puis le guide de contribution du projet.
  2. Signalez en commentaire que vous la prenez — cela évite que deux personnes fassent le même travail.
  3. Forkez le dépôt et travaillez sur une branche.
  4. Ouvrez une pull request qui référence le numéro de l'issue.

Évaluation

Cette issue n'a pas encore été évaluée.

Recevez les nouvelles issues par e-mail

Un résumé court des issues GitHub adaptées aux débutants.