From 2dc791eba924b1249a1fa1e83789d5de2654f56c Mon Sep 17 00:00:00 2001 From: Nicolas Kruchten Date: Sun, 10 Nov 2019 13:56:23 -0500 Subject: [PATCH 1/5] tweaks to look and feel of autodoc --- apidoc/_static/plotly-style.css | 16 ++++++++++++++++ apidoc/figure_factory.rst | 4 ++-- apidoc/graph_objects.rst | 12 +++++++----- apidoc/index.rst | 12 ++++++------ apidoc/io.rst | 2 +- apidoc/px.rst | 2 +- apidoc/subplots.rst | 2 +- 7 files changed, 34 insertions(+), 16 deletions(-) diff --git a/apidoc/_static/plotly-style.css b/apidoc/_static/plotly-style.css index 2163d78c9..3aa07cd68 100644 --- a/apidoc/_static/plotly-style.css +++ b/apidoc/_static/plotly-style.css @@ -11,3 +11,19 @@ .body { font-family: "Open Sans", sans-serif; } +.navbar-brand img { + height: 30px; + margin-top: 4px; +} + +.navbar .container { + padding-top: 8px; +} + +a { + color: #2391fe !important; +} + +code { + color: #2391fe !important; +} diff --git a/apidoc/figure_factory.rst b/apidoc/figure_factory.rst index 94aefb7c7..09b01b1a3 100644 --- a/apidoc/figure_factory.rst +++ b/apidoc/figure_factory.rst @@ -1,6 +1,6 @@ .. _ff: -Figure Factory +`plotly.figure_factory`: helper methods for building specific complex charts ============== .. currentmodule:: plotly.figure_factory @@ -23,6 +23,6 @@ Figure Factory create_streamline create_table create_ternary_contour - create_trisurf + create_trisurf create_violin diff --git a/apidoc/graph_objects.rst b/apidoc/graph_objects.rst index 525f9dedd..c1a4a7357 100644 --- a/apidoc/graph_objects.rst +++ b/apidoc/graph_objects.rst @@ -1,6 +1,6 @@ .. _graph-objects: -Graph objects: figures, traces and layout +`plotly.graph_objects`: low-level interface to figures, traces and layout ========================================= .. currentmodule:: plotly.graph_objects @@ -11,12 +11,14 @@ Graph objects: figures, traces and layout >>> import plotly.graph_objects as go -.. toctree:: - :maxdepth: 1 - :caption: Figure: +Figure +------ - figure.rst +.. autosummary:: + :toctree: generated/ + :template: trace.rst + Figure Layout ------ diff --git a/apidoc/index.rst b/apidoc/index.rst index c2a7d787d..463752036 100644 --- a/apidoc/index.rst +++ b/apidoc/index.rst @@ -3,7 +3,7 @@ You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. -plotly API reference +Python API reference for `plotly` ==================== This is the reference of plotly's API. Also see `plotly's documentation website `_. @@ -12,11 +12,11 @@ Submodules ---------- -* :ref:`Plotly express ` -* :ref:`Graph objects: figures, traces and layout ` -* :ref:`Subplots ` -* :ref:`Figure Factory ` -* :ref:`I/O ` +* :ref:`Plotly Express: high-level interface for data visualization ` +* :ref:`Graph Objects: low-level interface to figures, traces and layout ` +* :ref:`Subplots: helper function for layout out multi-plot figures ` +* :ref:`Figure Factories: helper methods for building specific complex charts ` +* :ref:`I/O: low-level interface for displaying, reading and writing figures ` Full reference list ------------------- diff --git a/apidoc/io.rst b/apidoc/io.rst index 296a77d5e..3fe4c0f2b 100644 --- a/apidoc/io.rst +++ b/apidoc/io.rst @@ -1,6 +1,6 @@ .. _io: -I/O +`plotly.io`: low-level interface for displaying, reading and writing figures ============== .. currentmodule:: plotly.io diff --git a/apidoc/px.rst b/apidoc/px.rst index 7873c72fc..45bccb7d1 100644 --- a/apidoc/px.rst +++ b/apidoc/px.rst @@ -1,6 +1,6 @@ .. _px: -Plotly express: `plotly.express` +`plotly.express`: high-level interface for data visualization ================================ The `plotly.express `_ module is diff --git a/apidoc/subplots.rst b/apidoc/subplots.rst index dbacf971b..1a7699c11 100644 --- a/apidoc/subplots.rst +++ b/apidoc/subplots.rst @@ -1,6 +1,6 @@ .. _subplots: -Subplots: `plotly.subplots` +`plotly.subplots`: helper function for layout out multi-plot figures =========================== .. currentmodule:: plotly.subplots From 974c8a34e59be524f3bcbf8f50ad870a9b9f1141 Mon Sep 17 00:00:00 2001 From: Emmanuelle Gouillart Date: Mon, 11 Nov 2019 11:27:54 -0500 Subject: [PATCH 2/5] longer underlines to avoid warnings --- apidoc/_templates/trace.rst | 4 ++-- apidoc/figure.rst | 21 --------------------- 2 files changed, 2 insertions(+), 23 deletions(-) delete mode 100644 apidoc/figure.rst diff --git a/apidoc/_templates/trace.rst b/apidoc/_templates/trace.rst index d4ff78fbe..6bd81c019 100644 --- a/apidoc/_templates/trace.rst +++ b/apidoc/_templates/trace.rst @@ -1,5 +1,5 @@ :mod:`{{module}}`.{{objname}} -{{ underline }} +{{ underline }}============================ .. currentmodule:: {{ module }} @@ -12,7 +12,7 @@ :mod:`{{module}}`.{{objname.lower()}} -{{ underline }} +{{ underline }}================================ .. autosummary:: diff --git a/apidoc/figure.rst b/apidoc/figure.rst deleted file mode 100644 index 62fb4155a..000000000 --- a/apidoc/figure.rst +++ /dev/null @@ -1,21 +0,0 @@ -Figure -====== - -.. currentmodule:: plotly.graph_objects - -.. autosummary:: - :toctree: generated/ - - Figure - - Figure.show - Figure.update_layout - Figure.add_traces - - -.. autoclass:: Figure - :members: - :inherited-members: - - -:ref:`base figure ` From f5504d97c36f66ab4c941120818d9c5f0727a03e Mon Sep 17 00:00:00 2001 From: Emmanuelle Gouillart Date: Mon, 11 Nov 2019 11:39:05 -0500 Subject: [PATCH 3/5] template for figure --- apidoc/_templates/class_figure.rst | 13 ++++--------- apidoc/graph_objects.rst | 5 +++-- 2 files changed, 7 insertions(+), 11 deletions(-) diff --git a/apidoc/_templates/class_figure.rst b/apidoc/_templates/class_figure.rst index b55f68b22..927b4a68b 100644 --- a/apidoc/_templates/class_figure.rst +++ b/apidoc/_templates/class_figure.rst @@ -5,7 +5,6 @@ .. currentmodule:: {{ module }} .. autoclass:: {{ objname }} - {% block methods %} .. automethod:: __init__ .. automethod:: show @@ -13,15 +12,11 @@ .. automethod:: add_traces {% endblock %} -Other methods -{{ underline }}============== - -.. autosummary:: - :toctree: generated/ - - plotly.graph_objects.{{ objname }} - +.. autoclass:: {{ objname }} + :members: + :inherited-members: .. raw:: html
+ diff --git a/apidoc/graph_objects.rst b/apidoc/graph_objects.rst index c1a4a7357..c2f9e527d 100644 --- a/apidoc/graph_objects.rst +++ b/apidoc/graph_objects.rst @@ -16,9 +16,10 @@ Figure .. autosummary:: :toctree: generated/ - :template: trace.rst + :template: class_figure.rst + + Figure - Figure Layout ------ From cd9408070e9885e5f859851a4577fdc61f628b2e Mon Sep 17 00:00:00 2001 From: Emmanuelle Gouillart Date: Mon, 11 Nov 2019 11:50:59 -0500 Subject: [PATCH 4/5] toc --- apidoc/graph_objects.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/apidoc/graph_objects.rst b/apidoc/graph_objects.rst index c2f9e527d..0286a863b 100644 --- a/apidoc/graph_objects.rst +++ b/apidoc/graph_objects.rst @@ -18,7 +18,7 @@ Figure :toctree: generated/ :template: class_figure.rst - Figure + Figure Layout From c31ef550a34bf8d5e098fd5c3063e74b3bbcedc3 Mon Sep 17 00:00:00 2001 From: Nicolas Kruchten Date: Mon, 11 Nov 2019 15:04:12 -0500 Subject: [PATCH 5/5] tweaks --- apidoc/_templates/class_figure.rst | 15 ++++++++++++--- apidoc/subplots.rst | 2 +- 2 files changed, 13 insertions(+), 4 deletions(-) diff --git a/apidoc/_templates/class_figure.rst b/apidoc/_templates/class_figure.rst index 927b4a68b..9c5fc37f8 100644 --- a/apidoc/_templates/class_figure.rst +++ b/apidoc/_templates/class_figure.rst @@ -4,14 +4,23 @@ .. currentmodule:: {{ module }} +.. autosummary:: + :toctree: generated/ + + Figure + + Figure.show + Figure.add_traces + Figure.update_traces + Figure.update_layout + + .. autoclass:: {{ objname }} {% block methods %} .. automethod:: __init__ - .. automethod:: show - .. automethod:: update_layout - .. automethod:: add_traces {% endblock %} + .. autoclass:: {{ objname }} :members: :inherited-members: diff --git a/apidoc/subplots.rst b/apidoc/subplots.rst index 1a7699c11..1f7de4fe6 100644 --- a/apidoc/subplots.rst +++ b/apidoc/subplots.rst @@ -1,6 +1,6 @@ .. _subplots: -`plotly.subplots`: helper function for layout out multi-plot figures +`plotly.subplots`: helper function for laying out multi-plot figures =========================== .. currentmodule:: plotly.subplots