Makefile: modify docstrings to use temporarily graph_objs

[emmanuelle]

This PR fixes the build of the API doc. The problem was that graph_objs objects have docstrings with intersphinx references like :class:plotly.graph_objects.scatter.Marker but (from my understanding, which might be incorrect) graph_objects are lazily imported and not found by sphinx when generating html files from the docstrings, hence no links were generated.

I solved the problem by temporarily changing the docstrings thanks to a massive sed, and reverting everything with git checkout after the sphinx build. A more robust long-term solution would be to have all the codegened code inside the graph_objects directory.

I tested that the solution works both on master and on the branch of #2403.

@nicolaskruchten @jonmmease

[nicolaskruchten]

lol for "massive sed" :)

So the output is the same as the current output? if you do a diff on the before and after trees it's reasonable?

[emmanuelle]

Hum how should I do the diff ? I cannot git diff with the version deployed on plotly.py-docs because we push -f and the histories of commits are disjoint. What I did to test was to explore the pages and follow the links, but it was indeed completely manual.

[emmanuelle]

The change of this PR modifies only docstrings so not the structure of the generated html pages (but the lazy import PR might have modified this structure).

[emmanuelle]

Oh wow I just saw you can do diff on linux on directories :-).

[emmanuelle]

So diffing the current API doc and the one generated on master results in a lot of changes. One reason for this is that the order of objects in the _all_ of submodules has systematically changed. For example compare https://github.com/plotly/plotly.py/blob/v4.6.0/packages/python/plotly/plotly/graph_objs/bar/__init__.py#L4113 (alphabetical order from what I can see) and https://github.com/plotly/plotly.py/blob/master/packages/python/plotly/plotly/graph_objs/bar/__init__.py#L21 (inverse alphabetical order).

I can dig further but maybe @jonmmease you would know why the order has changed?

[jonmmease]

Huh, no I don't think I had any good reason to change the sorting from alphabetical to reverse alphabetical. You could try sorting the classes and modules during code generation here:

plotly.py/packages/python/plotly/codegen/__init__.py

Lines 306 to 308 in 5b0e8d3

	for path_parts in datatype_rel_class_imports:
	rel_classes = datatype_rel_class_imports[path_parts]
	rel_modules = datatype_rel_module_imports.get(path_parts, [])

    for path_parts in datatype_rel_class_imports:
        rel_classes = sorted(datatype_rel_class_imports[path_parts])
        rel_modules = sorted(datatype_rel_module_imports.get(path_parts, []))

and see if that helps

[emmanuelle]

Thanks for the tip for the codegen @jonmmease , now the imports are indeed in alphabetical order and the API doc looks good :-). I also corrected a bug (related to graph_objects <-> graph_objs) which I had previously overlooked.

[emmanuelle]

Reviewing commit by commit will be easier, the middle commit is only codegen.

[nicolaskruchten]

Awesome! So the diff between current prod and the output of this branch is basically nil, right?

[nicolaskruchten]

💃