Apigen recursive (#2243)

* using sphinx-apidoc for generating the hierarchy of doc pages

* playing with templates

* autodoc for sphinx

* blacken

* also modified property functions

* changed :py:class: to :class:

* blacken

* revert changes to package-lock

* some fixes

* fix

* removed module from trace page

* revert template change

* title in template

Author: emmanuelle

.circleci/config.yml

@@ -409,7 +409,7 @@ jobs:
               cd ../../../doc
             fi
             echo 'export PATH="/home/circleci/project/doc/node_modules/.bin:$PATH"' >> $BASH_ENV
-            sudo apt-get install -y poppler-utils libxtst6 xvfb libgtk2.0-0 libgconf-2-4 libnss3 libasound2
+            sudo apt-get install -y poppler-utils libxtst6 xvfb libgtk2.0-0 libgconf-2-4 libnss3 libasound2 rename
             cd ..
 
       - save_cache:

doc/apidoc/Makefile

@@ -15,5 +15,10 @@ help:
 
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+# For sphinx-apidoc the first positional path is the module to document
+# then all the other ones are paths to exclude for the doc generation
 %: Makefile
+	sphinx-apidoc -o generated ../../packages/python/plotly/plotly ../../packages/python/plotly/plotly/validators ../../packages/python/plotly/plotly/tests ../../packages/python/plotly/plotly/matplotlylib/ ../../packages/python/plotly/plotly/offline ../../packages/python/plotly/plotly/api
 	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+	rename 's/graph_objs/graph_objects/' _build/html/*.html _build/html/generated/*.html
+	sed -i 's/graph_objs/graph_objects/g' _build/html/*.html _build/html/generated/*.html

doc/apidoc/_templates/class.rst

@@ -10,7 +10,6 @@
    .. automethod:: __init__
    {% endblock %}
 
-
 :mod:`{{module}}`.{{objname.lower()}}
 {{ underline }}================================
 
@@ -20,6 +19,7 @@
 
 .. automodule:: plotly.graph_objects.{{ objname.lower() }}
    :members:
+   :undoc-members:
 
 
 .. raw:: html

doc/apidoc/_templates/trace.rst

@@ -3,7 +3,7 @@
 `plotly.graph_objects`: low-level interface to figures, traces and layout
 =========================================
 
-.. currentmodule:: plotly.graph_objects
+.. currentmodule:: plotly.graph_objs
 
 :mod:`plotly.graph_objects` contains the building blocks of plotly :class:`Figure`: traces
 (:class:`Scatter`, :class:`Bar`, ...) and :class:`Layout`
@@ -31,7 +31,6 @@ Layout
    Layout
 
 
-
 Simple charts
 --------------
 

doc/apidoc/plotly.graph_objects.rst

@@ -2421,7 +2421,7 @@ def description(self):
             """\
     The '{plotly_name}' property is an instance of {class_str}
     that may be specified as:
-      - An instance of {module_str}.{class_str}
+      - An instance of :class:`{module_str}.{class_str}`
       - A dict of string/value properties that will be passed
         to the {class_str} constructor
 

packages/javascript/plotlywidget/package-lock.json

@@ -293,7 +293,7 @@ def __init__(self"""
         (
             f"arg",
             f"dict of properties compatible with this constructor "
-            f"or an instance of {class_name}",
+            f"or an instance of :class:`{class_name}`",
         )
     ]
 
@@ -321,7 +321,7 @@ def __init__(self"""
             raise ValueError(\"\"\"\\
 The first argument to the {class_name} 
 constructor must be a dict or 
-an instance of {class_name}\"\"\")
+an instance of :class:`{class_name}`\"\"\")
 
         # Handle skip_invalid
         # -------------------

packages/python/plotly/_plotly_utils/basevalidators.py

@@ -94,7 +94,7 @@ class {fig_classname}({base_classname}):\n"""
     def __init__(self, data=None, layout=None,
                  frames=None, skip_invalid=False, **kwargs):
         \"\"\"
-        Create a new {fig_classname} instance
+        Create a new :class:{fig_classname} instance
         
         Parameters
         ----------

packages/python/plotly/codegen/datatypes.py

@@ -941,7 +941,7 @@ def get_constructor_params_docstring(self, indent=12):
                         f"{subtype_node.name_datatype_class}"
                     )
                 subtype_description = (
-                    f"A tuple of {class_name} instances or "
+                    f"A tuple of :class:`{class_name}` instances or "
                     "dicts with compatible properties"
                 )
             elif subtype_node.is_compound:
@@ -958,7 +958,7 @@ def get_constructor_params_docstring(self, indent=12):
                     )
 
                 subtype_description = (
-                    f"{class_name} instance or dict with compatible properties"
+                    f":class:`{class_name}` instance or dict with compatible properties"
                 )
             else:
                 subtype_description = ""

packages/python/plotly/codegen/figure.py

@@ -536,5 +536,5 @@ def make_docstring(fn, override_dict={}):
         param_type = param_doc[0]
         result += "%s: %s\n%s\n" % (param, param_type, param_desc)
     result += "\nReturns\n-------\n"
-    result += "    A `Figure` object."
+    result += "    plotly.graph_objects.Figure"
     return result