diff --git a/.circleci/config.yml b/.circleci/config.yml index 7028edb05..8e17569e0 100644 --- a/.circleci/config.yml +++ b/.circleci/config.yml @@ -68,7 +68,32 @@ jobs: tar -zcf build/html.tgz build/html rm -rf build/html build/ipynb + - run: + name: make doc + command: | + . venv/bin/activate + cd apidoc + make html + if [ "${CIRCLE_BRANCH}" == "master" ]; then + cd _build/html + git init + git config user.name nicolaskruchten + git config user.email nicolas@plot.ly + git add * + git commit -m build + git push --force git@github.com:plotly/plotly.py-docs.git master:gh-pages + rm -rf .git + cd ../.. + fi + + cd .. + - store_artifacts: path: build destination: build + + + - store_artifacts: + path: apidoc/_build/html + destination: apidoc diff --git a/apidoc/Makefile b/apidoc/Makefile new file mode 100644 index 000000000..8b64b1e99 --- /dev/null +++ b/apidoc/Makefile @@ -0,0 +1,19 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXOPTS = +SPHINXBUILD = python3 -m sphinx +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) diff --git a/apidoc/README.rst b/apidoc/README.rst new file mode 100644 index 000000000..d210288c6 --- /dev/null +++ b/apidoc/README.rst @@ -0,0 +1 @@ +make html diff --git a/apidoc/_static/logo.png b/apidoc/_static/logo.png new file mode 100644 index 000000000..10db04a63 Binary files /dev/null and b/apidoc/_static/logo.png differ diff --git a/apidoc/_templates/class.rst b/apidoc/_templates/class.rst new file mode 100644 index 000000000..494293e1c --- /dev/null +++ b/apidoc/_templates/class.rst @@ -0,0 +1,15 @@ +:mod:`{{module}}`.{{objname}} +{{ underline }}============== + +.. currentmodule:: {{ module }} + +.. autoclass:: {{ objname }} + + {% block methods %} + .. automethod:: __init__ + {% endblock %} + + +.. raw:: html + +
diff --git a/apidoc/_templates/class_figure.rst b/apidoc/_templates/class_figure.rst new file mode 100644 index 000000000..b55f68b22 --- /dev/null +++ b/apidoc/_templates/class_figure.rst @@ -0,0 +1,27 @@ +:mod:`{{module}}`.{{objname}} +{{ underline }}============== + + +.. currentmodule:: {{ module }} + +.. autoclass:: {{ objname }} + + {% block methods %} + .. automethod:: __init__ + .. automethod:: show + .. automethod:: update_layout + .. automethod:: add_traces + {% endblock %} + +Other methods +{{ underline }}============== + +.. autosummary:: + :toctree: generated/ + + plotly.graph_objects.{{ objname }} + + +.. raw:: html + +
diff --git a/apidoc/_templates/function.rst b/apidoc/_templates/function.rst new file mode 100644 index 000000000..b81cd41a9 --- /dev/null +++ b/apidoc/_templates/function.rst @@ -0,0 +1,11 @@ +:mod:`{{module}}`.{{objname}} +{{ underline }}==================== + +.. currentmodule:: {{ module }} + +.. autofunction:: {{ objname }} + + +.. raw:: html + +
diff --git a/apidoc/_templates/trace.rst b/apidoc/_templates/trace.rst new file mode 100644 index 000000000..1fae91777 --- /dev/null +++ b/apidoc/_templates/trace.rst @@ -0,0 +1,28 @@ +:mod:`{{module}}`.{{objname}} +{{ underline }} + + +.. currentmodule:: {{ module }} + +.. autoclass:: {{ objname }} + + {% block methods %} + .. automethod:: __init__ + {% endblock %} + + +:mod:`{{module}}`.{{objname.lower()}} +{{ underline }} + +.. autosummary:: + :toctree: generated/ + + plotly.graph_objects.{{ objname.lower() }} + +.. automodule:: plotly.graph_objects.{{ objname.lower() }} + :members: + + +.. raw:: html + +
diff --git a/apidoc/conf.py b/apidoc/conf.py new file mode 100644 index 000000000..39a3460f4 --- /dev/null +++ b/apidoc/conf.py @@ -0,0 +1,203 @@ +# -*- 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' + +source_parsers = {".md": "recommonmark.parser.CommonMarkParser"} +# 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 = { + #'nosidebar': True, + 'analytics_id':'UA-39373211-1', + 'logo':'logo.png', + 'page_width': '70%', + 'sidebar_width':'15%' + } + +# 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/apidoc/figure.rst b/apidoc/figure.rst new file mode 100644 index 000000000..56ecd9bc2 --- /dev/null +++ b/apidoc/figure.rst @@ -0,0 +1,17 @@ +Figure +====== + +.. currentmodule:: plotly.graph_objects + +.. autosummary:: + :toctree: generated/ + + Figure + + Figure.show + Figure.update_layout + Figure.add_traces + + +.. autoclass:: Figure + :members: diff --git a/apidoc/figure_factory.rst b/apidoc/figure_factory.rst new file mode 100644 index 000000000..94aefb7c7 --- /dev/null +++ b/apidoc/figure_factory.rst @@ -0,0 +1,28 @@ +.. _ff: + +Figure Factory +============== + +.. currentmodule:: plotly.figure_factory + +.. autosummary:: + :toctree: generated/ + :template: function.rst + + 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/apidoc/graph_objects.rst b/apidoc/graph_objects.rst new file mode 100644 index 000000000..a7a9b89a5 --- /dev/null +++ b/apidoc/graph_objects.rst @@ -0,0 +1,121 @@ +.. _graph-objects: + +Graph objects: figures, traces and layout +========================================= + +.. currentmodule:: plotly.graph_objects + +:mod:`plotly.graph_objects` contains the building blocks of plotly :class:`Figure`: traces +(:class:`Scatter`, :class:`Bar`, ...) and :class:`Layout` +:: + + >>> import plotly.graph_objects as go + +.. toctree:: + :maxdepth: 1 + :caption: Figure: + + figure.rst + + +Layout +------ + +.. autosummary:: + :toctree: generated/ + :template: trace.rst + + Layout + + + +Simple charts +-------------- + +.. autosummary:: + :toctree: generated/ + :template: trace.rst + + Scatter + Scattergl + Bar + Pie + Heatmap + Contour + Table + +Distributions +------------- + +.. autosummary:: + :toctree: generated/ + :template: trace.rst + + Box + Violin + Histogram + Histogram2d + Histogram2dcontour + +Finance +------- + +.. autosummary:: + :toctree: generated/ + :template: trace.rst + + Ohlc + Candlestick + Waterfall + Funnel + Funnelarea + Indicator + +3D +-- + +.. autosummary:: + :toctree: generated/ + :template: trace.rst + + Scatter3d + Surface + Mesh3d + Cone + Streamtube + Volume + Isosurface + +Maps +---- + +.. autosummary:: + :toctree: generated/ + :template: trace.rst + + Scattergeo + Choropleth + Scattermapbox + Choroplethmapbox + Densitymapbox + +Specialized +----------- + +.. autosummary:: + :toctree: generated/ + :template: trace.rst + + Scatterpolar + Scatterpolargl + Barpolar + Scatterternary + Sunburst + Treemap + Sankey + Splom + Parcats + Parcoords + Carpet + Scattercarpet + Contourcarpet diff --git a/apidoc/helper_go_names.py b/apidoc/helper_go_names.py new file mode 100644 index 000000000..0a5621023 --- /dev/null +++ b/apidoc/helper_go_names.py @@ -0,0 +1,34 @@ +import inspect +import plotly.graph_objects as go + +members = inspect.getmembers(go) + +functions, classes, submodules = [], [], [] + +for m in members: + print(m) + if m[0] not in go.__all__: + continue + if m[1].__doc__ and 'is deprecated' in m[1].__doc__: + continue + elif inspect.isfunction(m[1]): + functions.append(m[0]) + elif inspect.isclass(m[1]): + classes.append(m[0]) + elif inspect.ismodule(m[1]): + submodules.append(m[0]) + +classes.sort() +submodules.sort() + +classes_str = "\n".join(classes) +# print(classes_str) + +submodules_str = "\n".join(submodules) +# print(submodules_str) + +autosubmodule = '' + +for submodule in submodules: + autosubmodule += '.. automodule:: plotly.graph_objects.%s\n :members:\n\n' %submodule +print(autosubmodule) diff --git a/apidoc/index.rst b/apidoc/index.rst new file mode 100644 index 000000000..c2a7d787d --- /dev/null +++ b/apidoc/index.rst @@ -0,0 +1,40 @@ +.. 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. + +plotly API reference +==================== + +This is the reference of plotly's API. Also see `plotly's documentation website `_. + +Submodules +---------- + + +* :ref:`Plotly express ` +* :ref:`Graph objects: figures, traces and layout ` +* :ref:`Subplots ` +* :ref:`Figure Factory ` +* :ref:`I/O ` + +Full reference list +------------------- + +.. toctree:: + :maxdepth: 3 + + px.rst + graph_objects.rst + subplots.rst + figure_factory.rst + io.rst + + + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` diff --git a/apidoc/io.rst b/apidoc/io.rst new file mode 100644 index 000000000..c241ff703 --- /dev/null +++ b/apidoc/io.rst @@ -0,0 +1,27 @@ +.. _io: + +I/O +============== + +.. currentmodule:: plotly.io + +.. autosummary:: + :toctree: generated/ + :template: function.rst + + 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/apidoc/px.rst b/apidoc/px.rst new file mode 100644 index 000000000..7873c72fc --- /dev/null +++ b/apidoc/px.rst @@ -0,0 +1,44 @@ +.. _px: + +Plotly express: `plotly.express` +================================ + +The `plotly.express `_ module is +plotly's high-level API for rapid figure generation. :: + + >>> import plotly.express as px + +.. currentmodule:: plotly.express + +.. autosummary:: + :toctree: generated/ + :template: function.rst + + 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 + + + diff --git a/apidoc/subplots.rst b/apidoc/subplots.rst new file mode 100644 index 000000000..dbacf971b --- /dev/null +++ b/apidoc/subplots.rst @@ -0,0 +1,16 @@ +.. _subplots: + +Subplots: `plotly.subplots` +=========================== + +.. currentmodule:: plotly.subplots + +.. autosummary:: + :toctree: generated/ + :template: function.rst + + make_subplots + + +.. autofunction:: plotly.subplots.make_subplots + diff --git a/requirements.txt b/requirements.txt index d701fb73f..9b801efa7 100644 --- a/requirements.txt +++ b/requirements.txt @@ -17,3 +17,5 @@ requests networkx squarify scikit-image +sphinx +recommonmark