Apigen recursive

[emmanuelle]

still WIP, and it's been some time since I worked on this. Basically the idea is to call sphinx-apidoc to generate all the doc pages.

[nicolaskruchten]

the changes to this file probably should be reverted.

[emmanuelle]

@jonmmease, one thing I can't get my head around is which part of the codegen generates the docstrings of the @property methods, for example https://github.com/plotly/plotly.py/blob/master/packages/python/plotly/plotly/graph_objs/bar/hoverlabel/__init__.py#L67. For the docstrings of the constructors I found how to hack them to add the :py:func: directives creating internal links with sphinx, but not for the @property methods.

[emmanuelle]

The doc build is a bit long (a few minutes), but the build is stored in the artifacts of CircleCI if you want to take a look.

[jonmmease]

@emmanuelle, the property docstrings are generated dynamically during codegen by Validator instances. Check out the description method of the validator classes in packages/python/plotly/_plotly_utils/basevalidators.py. Does that help?

[emmanuelle]

@jonmmease absolutely! I was grepping only the codegen directory, I should have known better :-). Thanks a lot!

[nicolaskruchten]

So with this PR we get these extra directives in the docstrings that people will see when they try help(object) in a notebook?

[emmanuelle]

@nicolaskruchten yes we'll have the extra directives. However I found out that we can use :class: instead of :py:class: which is a bit shorter :-).

[nicolaskruchten]

I can live with :class in the docstrings... @jonmmease objections?

[emmanuelle]

I could also attach a helper function to autodoc-process-docstring as described in https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html or https://chromium.googlesource.com/infra/third_party/sphinxcontrib_napoleon/+/refs/heads/master/sphinxcontrib/napoleon/__init__.py#253 in order to prepend the :class: to plotly.graph_objects.xx strings. But this can also be done later on :-).

[emmanuelle]

Ready for review!

[nicolaskruchten]

redundant?

[emmanuelle]

hum let me fix this

[nicolaskruchten]

💃 ! This is great :)