From 4997b5b79e84d96fce4b92f745f1b350742f6d36 Mon Sep 17 00:00:00 2001 From: Emmanuelle Gouillart Date: Wed, 2 Oct 2019 22:08:57 -0400 Subject: [PATCH 1/3] rough generation of API doc --- doc/Makefile | 19 ++ doc/README.rst | 1 + doc/conf.py | 194 ++++++++++++++++++ doc/figure_factory.rst | 27 +++ doc/graph_objects.rst | 6 + doc/index.rst | 25 +++ doc/io.rst | 23 +++ doc/px.rst | 36 ++++ .../plotly/plotly/figure_factory/__init__.py | 17 ++ .../python/plotly/plotly/graph_objects.py | 2 + .../plotly/plotly/graph_objs/__init__.py | 2 + packages/python/plotly/plotly/io/__init__.py | 6 + 12 files changed, 358 insertions(+) create mode 100644 doc/Makefile create mode 100644 doc/README.rst create mode 100644 doc/conf.py create mode 100644 doc/figure_factory.rst create mode 100644 doc/graph_objects.rst create mode 100644 doc/index.rst create mode 100644 doc/io.rst create mode 100644 doc/px.rst diff --git a/doc/Makefile b/doc/Makefile new file mode 100644 index 00000000000..298ea9e213e --- /dev/null +++ b/doc/Makefile @@ -0,0 +1,19 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXOPTS = +SPHINXBUILD = sphinx-build +SOURCEDIR = . +BUILDDIR = _build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) \ No newline at end of file diff --git a/doc/README.rst b/doc/README.rst new file mode 100644 index 00000000000..d210288c6c7 --- /dev/null +++ b/doc/README.rst @@ -0,0 +1 @@ +make html diff --git a/doc/conf.py b/doc/conf.py new file mode 100644 index 00000000000..fb2e0f0406d --- /dev/null +++ b/doc/conf.py @@ -0,0 +1,194 @@ +# -*- coding: utf-8 -*- +# +# Configuration file for the Sphinx documentation builder. +# +# This file does only contain a selection of the most common options. For a +# full list see the documentation: +# http://www.sphinx-doc.org/en/master/config + +# -- Path setup -------------------------------------------------------------- + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +# +import os +import sys +sys.path.insert(0, os.path.abspath('../packages/python/plotly')) + + +# -- Project information ----------------------------------------------------- + +project = 'plotly' +copyright = '2019, plotly team' +author = 'plotly team' + +# The short X.Y version +version = '' +# The full version, including alpha/beta/rc tags +release = '4.2' + + +# -- General configuration --------------------------------------------------- + +# If your documentation needs a minimal Sphinx version, state it here. +# +# needs_sphinx = '1.0' + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = [ + 'sphinx.ext.autodoc', + 'sphinx.ext.autosummary', + 'sphinx.ext.intersphinx', + 'sphinx.ext.todo', + 'sphinx.ext.coverage', + 'sphinx.ext.napoleon' +] + +autosummary_generate = True + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# The suffix(es) of source filenames. +# You can specify multiple suffix as a list of string: +# +# source_suffix = ['.rst', '.md'] +source_suffix = '.rst' + +# The master toctree document. +master_doc = 'index' + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +# +# This is also used if you do content translation via gettext catalogs. +# Usually you set "language" from the command line for these cases. +language = None + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This pattern also affects html_static_path and html_extra_path. +exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = None + + +# -- Options for HTML output ------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# +html_theme = 'alabaster' + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +# +# html_theme_options = {} + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['_static'] + +# Custom sidebar templates, must be a dictionary that maps document names +# to template names. +# +# The default sidebars (for documents that don't match any pattern) are +# defined by theme itself. Builtin themes are using these templates by +# default: ``['localtoc.html', 'relations.html', 'sourcelink.html', +# 'searchbox.html']``. +# +# html_sidebars = {} + + +# -- Options for HTMLHelp output --------------------------------------------- + +# Output file base name for HTML help builder. +htmlhelp_basename = 'plotlydoc' + + +# -- Options for LaTeX output ------------------------------------------------ + +latex_elements = { + # The paper size ('letterpaper' or 'a4paper'). + # + # 'papersize': 'letterpaper', + + # The font size ('10pt', '11pt' or '12pt'). + # + # 'pointsize': '10pt', + + # Additional stuff for the LaTeX preamble. + # + # 'preamble': '', + + # Latex figure (float) alignment + # + # 'figure_align': 'htbp', +} + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, +# author, documentclass [howto, manual, or own class]). +latex_documents = [ + (master_doc, 'plotly.tex', 'plotly Documentation', + 'plotly team', 'manual'), +] + + +# -- Options for manual page output ------------------------------------------ + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + (master_doc, 'plotly', 'plotly Documentation', + [author], 1) +] + + +# -- Options for Texinfo output ---------------------------------------------- + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +texinfo_documents = [ + (master_doc, 'plotly', 'plotly Documentation', + author, 'plotly', 'One line description of project.', + 'Miscellaneous'), +] + + +# -- Options for Epub output ------------------------------------------------- + +# Bibliographic Dublin Core info. +epub_title = project + +# The unique identifier of the text. This can be a ISBN number +# or the project homepage. +# +# epub_identifier = '' + +# A unique identification for the text. +# +# epub_uid = '' + +# A list of files that should not be packed into the epub file. +epub_exclude_files = ['search.html'] + + +# -- Extension configuration ------------------------------------------------- + +# -- Options for intersphinx extension --------------------------------------- + +# Example configuration for intersphinx: refer to the Python standard library. +intersphinx_mapping = {'https://docs.python.org/': None} + +# -- Options for todo extension ---------------------------------------------- + +# If true, `todo` and `todoList` produce output, else they produce nothing. +todo_include_todos = True diff --git a/doc/figure_factory.rst b/doc/figure_factory.rst new file mode 100644 index 00000000000..a2aaf1693a2 --- /dev/null +++ b/doc/figure_factory.rst @@ -0,0 +1,27 @@ +Figure Factory +============== + +.. currentmodule:: plotly.figure_factory + +.. autosummary:: + + create_2d_density + create_annotated_heatmap + create_bullet + create_candlestick + create_dendrogram + create_distplot + create_facet_grid + create_gantt + create_ohlc + create_quiver + create_scatterplotmatrix + create_streamline + create_table + create_ternary_contour + create_trisurf + create_violin + +.. automodule:: plotly.figure_factory + :members: + diff --git a/doc/graph_objects.rst b/doc/graph_objects.rst new file mode 100644 index 00000000000..daf47ba27fa --- /dev/null +++ b/doc/graph_objects.rst @@ -0,0 +1,6 @@ +GO +=== + +.. automodule:: plotly.graph_objects + :members: + diff --git a/doc/index.rst b/doc/index.rst new file mode 100644 index 00000000000..58b73f23bf1 --- /dev/null +++ b/doc/index.rst @@ -0,0 +1,25 @@ +.. plotly documentation master file, created by + sphinx-quickstart on Wed Oct 2 12:55:48 2019. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Welcome to plotly's documentation! +================================== + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + + px.rst + graph_objects.rst + figure_factory.rst + io.rst + + + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` diff --git a/doc/io.rst b/doc/io.rst new file mode 100644 index 00000000000..975c09b9f3b --- /dev/null +++ b/doc/io.rst @@ -0,0 +1,23 @@ +I/O +============== + +.. currentmodule:: plotly.io + +.. autosummary:: + + to_image + write_image + to_json + from_json + read_json + write_json + templates + to_templated + to_html + write_html + renderers + show + +.. automodule:: plotly.io + :members: + diff --git a/doc/px.rst b/doc/px.rst new file mode 100644 index 00000000000..785560a09e0 --- /dev/null +++ b/doc/px.rst @@ -0,0 +1,36 @@ +Plotly express +============== + +.. currentmodule:: plotly.express + +.. autosummary:: + scatter + scatter_3d + scatter_polar + scatter_ternary + scatter_mapbox + scatter_geo + line + line_3d + line_polar + line_ternary + line_mapbox + line_geo + area + bar + bar_polar + violin + box + strip + histogram + scatter_matrix + parallel_coordinates + parallel_categories + choropleth + density_contour + density_heatmap + + +.. automodule:: plotly.express + :members: + diff --git a/packages/python/plotly/plotly/figure_factory/__init__.py b/packages/python/plotly/plotly/figure_factory/__init__.py index 6ce7217803e..f77c9914e1f 100644 --- a/packages/python/plotly/plotly/figure_factory/__init__.py +++ b/packages/python/plotly/plotly/figure_factory/__init__.py @@ -30,3 +30,20 @@ if optional_imports.get_module("pandas") is not None: from plotly.figure_factory._county_choropleth import create_choropleth + +__all__ = ["create_2d_density", + "create_annotated_heatmap", + "create_bullet", + "create_candlestick", + "create_dendrogram", + "create_distplot", + "create_facet_grid", + "create_gantt", + "create_ohlc", + "create_quiver", + "create_scatterplotmatrix", + "create_streamline", + "create_table", + "create_ternary_contour", + "create_trisurf", + "create_violin"] diff --git a/packages/python/plotly/plotly/graph_objects.py b/packages/python/plotly/plotly/graph_objects.py index 406bd66fd8d..09575091d52 100644 --- a/packages/python/plotly/plotly/graph_objects.py +++ b/packages/python/plotly/plotly/graph_objects.py @@ -1,2 +1,4 @@ from __future__ import absolute_import from plotly.graph_objs import * + +__all__ = ["Scatter", "Bar"] diff --git a/packages/python/plotly/plotly/graph_objs/__init__.py b/packages/python/plotly/plotly/graph_objs/__init__.py index d66925a16de..3ebab80dbf4 100644 --- a/packages/python/plotly/plotly/graph_objs/__init__.py +++ b/packages/python/plotly/plotly/graph_objs/__init__.py @@ -92739,3 +92739,5 @@ def __init__( Trace, Histogram2dcontour, ) + +__all__ = ["Scatter", "Bar"] diff --git a/packages/python/plotly/plotly/io/__init__.py b/packages/python/plotly/plotly/io/__init__.py index 63a30e8456e..bfe6c0a77da 100644 --- a/packages/python/plotly/plotly/io/__init__.py +++ b/packages/python/plotly/plotly/io/__init__.py @@ -10,3 +10,9 @@ from ._renderers import renderers, show from . import base_renderers + +__all__ = ["to_image", "write_image", + "to_json", "from_json", "read_json", "write_json", + "templates", "to_templated", + "to_html", "write_html", + "renderers", "show", "base_renderers"] From 95721f1e3c4bcfe4efb3b5b2a3850a8bf3fae106 Mon Sep 17 00:00:00 2001 From: Emmanuelle Gouillart Date: Wed, 2 Oct 2019 22:14:17 -0400 Subject: [PATCH 2/3] black --- doc/conf.py | 66 +++++++++---------- .../plotly/plotly/figure_factory/__init__.py | 34 +++++----- packages/python/plotly/plotly/io/__init__.py | 20 ++++-- 3 files changed, 66 insertions(+), 54 deletions(-) diff --git a/doc/conf.py b/doc/conf.py index fb2e0f0406d..6f483890ee5 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -14,19 +14,20 @@ # import os import sys -sys.path.insert(0, os.path.abspath('../packages/python/plotly')) + +sys.path.insert(0, os.path.abspath("../packages/python/plotly")) # -- Project information ----------------------------------------------------- -project = 'plotly' -copyright = '2019, plotly team' -author = 'plotly team' +project = "plotly" +copyright = "2019, plotly team" +author = "plotly team" # The short X.Y version -version = '' +version = "" # The full version, including alpha/beta/rc tags -release = '4.2' +release = "4.2" # -- General configuration --------------------------------------------------- @@ -39,27 +40,27 @@ # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. extensions = [ - 'sphinx.ext.autodoc', - 'sphinx.ext.autosummary', - 'sphinx.ext.intersphinx', - 'sphinx.ext.todo', - 'sphinx.ext.coverage', - 'sphinx.ext.napoleon' + "sphinx.ext.autodoc", + "sphinx.ext.autosummary", + "sphinx.ext.intersphinx", + "sphinx.ext.todo", + "sphinx.ext.coverage", + "sphinx.ext.napoleon", ] autosummary_generate = True # Add any paths that contain templates here, relative to this directory. -templates_path = ['_templates'] +templates_path = ["_templates"] # The suffix(es) of source filenames. # You can specify multiple suffix as a list of string: # # source_suffix = ['.rst', '.md'] -source_suffix = '.rst' +source_suffix = ".rst" # The master toctree document. -master_doc = 'index' +master_doc = "index" # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. @@ -71,7 +72,7 @@ # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. # This pattern also affects html_static_path and html_extra_path. -exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] +exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"] # The name of the Pygments (syntax highlighting) style to use. pygments_style = None @@ -82,7 +83,7 @@ # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. # -html_theme = 'alabaster' +html_theme = "alabaster" # Theme options are theme-specific and customize the look and feel of a theme # further. For a list of options available for each theme, see the @@ -93,7 +94,7 @@ # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". -html_static_path = ['_static'] +html_static_path = ["_static"] # Custom sidebar templates, must be a dictionary that maps document names # to template names. @@ -109,7 +110,7 @@ # -- Options for HTMLHelp output --------------------------------------------- # Output file base name for HTML help builder. -htmlhelp_basename = 'plotlydoc' +htmlhelp_basename = "plotlydoc" # -- Options for LaTeX output ------------------------------------------------ @@ -118,15 +119,12 @@ # The paper size ('letterpaper' or 'a4paper'). # # 'papersize': 'letterpaper', - # The font size ('10pt', '11pt' or '12pt'). # # 'pointsize': '10pt', - # Additional stuff for the LaTeX preamble. # # 'preamble': '', - # Latex figure (float) alignment # # 'figure_align': 'htbp', @@ -136,8 +134,7 @@ # (source start file, target name, title, # author, documentclass [howto, manual, or own class]). latex_documents = [ - (master_doc, 'plotly.tex', 'plotly Documentation', - 'plotly team', 'manual'), + (master_doc, "plotly.tex", "plotly Documentation", "plotly team", "manual") ] @@ -145,10 +142,7 @@ # One entry per manual page. List of tuples # (source start file, name, description, authors, manual section). -man_pages = [ - (master_doc, 'plotly', 'plotly Documentation', - [author], 1) -] +man_pages = [(master_doc, "plotly", "plotly Documentation", [author], 1)] # -- Options for Texinfo output ---------------------------------------------- @@ -157,9 +151,15 @@ # (source start file, target name, title, author, # dir menu entry, description, category) texinfo_documents = [ - (master_doc, 'plotly', 'plotly Documentation', - author, 'plotly', 'One line description of project.', - 'Miscellaneous'), + ( + master_doc, + "plotly", + "plotly Documentation", + author, + "plotly", + "One line description of project.", + "Miscellaneous", + ) ] @@ -178,7 +178,7 @@ # epub_uid = '' # A list of files that should not be packed into the epub file. -epub_exclude_files = ['search.html'] +epub_exclude_files = ["search.html"] # -- Extension configuration ------------------------------------------------- @@ -186,7 +186,7 @@ # -- Options for intersphinx extension --------------------------------------- # Example configuration for intersphinx: refer to the Python standard library. -intersphinx_mapping = {'https://docs.python.org/': None} +intersphinx_mapping = {"https://docs.python.org/": None} # -- Options for todo extension ---------------------------------------------- diff --git a/packages/python/plotly/plotly/figure_factory/__init__.py b/packages/python/plotly/plotly/figure_factory/__init__.py index f77c9914e1f..2b686c8ce3e 100644 --- a/packages/python/plotly/plotly/figure_factory/__init__.py +++ b/packages/python/plotly/plotly/figure_factory/__init__.py @@ -31,19 +31,21 @@ if optional_imports.get_module("pandas") is not None: from plotly.figure_factory._county_choropleth import create_choropleth -__all__ = ["create_2d_density", - "create_annotated_heatmap", - "create_bullet", - "create_candlestick", - "create_dendrogram", - "create_distplot", - "create_facet_grid", - "create_gantt", - "create_ohlc", - "create_quiver", - "create_scatterplotmatrix", - "create_streamline", - "create_table", - "create_ternary_contour", - "create_trisurf", - "create_violin"] +__all__ = [ + "create_2d_density", + "create_annotated_heatmap", + "create_bullet", + "create_candlestick", + "create_dendrogram", + "create_distplot", + "create_facet_grid", + "create_gantt", + "create_ohlc", + "create_quiver", + "create_scatterplotmatrix", + "create_streamline", + "create_table", + "create_ternary_contour", + "create_trisurf", + "create_violin", +] diff --git a/packages/python/plotly/plotly/io/__init__.py b/packages/python/plotly/plotly/io/__init__.py index bfe6c0a77da..6b96585c334 100644 --- a/packages/python/plotly/plotly/io/__init__.py +++ b/packages/python/plotly/plotly/io/__init__.py @@ -11,8 +11,18 @@ from . import base_renderers -__all__ = ["to_image", "write_image", - "to_json", "from_json", "read_json", "write_json", - "templates", "to_templated", - "to_html", "write_html", - "renderers", "show", "base_renderers"] +__all__ = [ + "to_image", + "write_image", + "to_json", + "from_json", + "read_json", + "write_json", + "templates", + "to_templated", + "to_html", + "write_html", + "renderers", + "show", + "base_renderers", +] From cc6201e667998ebac34cd9fa046bdeabba82dd10 Mon Sep 17 00:00:00 2001 From: Emmanuelle Gouillart Date: Wed, 2 Oct 2019 22:56:40 -0400 Subject: [PATCH 3/3] all --- packages/python/plotly/plotly/graph_objects.py | 17 ++++++++++++++++- .../python/plotly/plotly/graph_objs/__init__.py | 1 - 2 files changed, 16 insertions(+), 2 deletions(-) diff --git a/packages/python/plotly/plotly/graph_objects.py b/packages/python/plotly/plotly/graph_objects.py index 09575091d52..2bc0611c3cf 100644 --- a/packages/python/plotly/plotly/graph_objects.py +++ b/packages/python/plotly/plotly/graph_objects.py @@ -1,4 +1,19 @@ from __future__ import absolute_import from plotly.graph_objs import * -__all__ = ["Scatter", "Bar"] +__all__ = [ + "Scatter", + "ScatterGL", + "Bar", + "Heatmap", + "Contour", + "Table", + "Figure", + "Layout", + "Pie", + "Box", + "Violin", + "Histogram", + "Volume", + "Isosurface", +] diff --git a/packages/python/plotly/plotly/graph_objs/__init__.py b/packages/python/plotly/plotly/graph_objs/__init__.py index 3ebab80dbf4..a3df954f9f0 100644 --- a/packages/python/plotly/plotly/graph_objs/__init__.py +++ b/packages/python/plotly/plotly/graph_objs/__init__.py @@ -92740,4 +92740,3 @@ def __init__( Histogram2dcontour, ) -__all__ = ["Scatter", "Bar"]