Better magic_underscore explanation in docstrings

[nicolaskruchten]

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?

[emmanuelle]

You mean document the fact that for example in go.Scatter we can pass marker= but alos marker_color=?

[nicolaskruchten]

Yep!