plotly / plotly/plotly.py

Better magic_underscore explanation in docstrings

Abierto
#1,925 2 comentarios 0 reacciones 1 asignado Ver en GitHub

@nicholas-esterer ya está trabajando en esto.

Desde el 13/10/2020.

documentation feature P3
Lenguaje dominante
Python
Estrellas
18.8k
Forks
2.8k
Merge medio
16 h 26 min
PR fusionados (30 d)
21

Descripción

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?

Guía de contribución

Abrir la guía de contribución

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Evaluación

Este issue todavía no se ha evaluado.

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.