Skip to content

Commit db09d20

Browse files
emmanuelleemmanuelle
authored
Autodoc for the API (#134)
1 parent 7177840 commit db09d20

18 files changed

+658
-0
lines changed

‎.circleci/config.yml

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -68,7 +68,32 @@ jobs:
6868
tar -zcf build/html.tgz build/html
6969
rm -rf build/html build/ipynb
7070
71+
- run:
72+
name: make doc
73+
command: |
74+
. venv/bin/activate
75+
cd apidoc
76+
make html
77+
if [ "${CIRCLE_BRANCH}" == "master" ]; then
78+
cd _build/html
79+
git init
80+
git config user.name nicolaskruchten
81+
git config user.email nicolas@plot.ly
82+
git add *
83+
git commit -m build
84+
git push --force git@github.com:plotly/plotly.py-docs.git master:gh-pages
85+
rm -rf .git
86+
cd ../..
87+
fi
88+
89+
cd ..
90+
7191
7292
- store_artifacts:
7393
path: build
7494
destination: build
95+
96+
97+
- store_artifacts:
98+
path: apidoc/_build/html
99+
destination: apidoc

‎apidoc/Makefile

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
# Minimal makefile for Sphinx documentation
2+
#
3+
4+
# You can set these variables from the command line.
5+
SPHINXOPTS =
6+
SPHINXBUILD = python3 -m sphinx
7+
SOURCEDIR = .
8+
BUILDDIR = _build
9+
10+
# Put it first so that "make" without argument is like "make help".
11+
help:
12+
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
13+
14+
.PHONY: help Makefile
15+
16+
# Catch-all target: route all unknown targets to Sphinx using the new
17+
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
18+
%: Makefile
19+
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

‎apidoc/README.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
make html

‎apidoc/_static/logo.png

8.1 KB
Loading

‎apidoc/_templates/class.rst

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
:mod:`{{module}}`.{{objname}}
2+
{{ underline }}==============
3+
4+
.. currentmodule:: {{ module }}
5+
6+
.. autoclass:: {{ objname }}
7+
8+
{% block methods %}
9+
.. automethod:: __init__
10+
{% endblock %}
11+
12+
13+
.. raw:: html
14+
15+
<div class="clearer"></div>

‎apidoc/_templates/class_figure.rst

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
:mod:`{{module}}`.{{objname}}
2+
{{ underline }}==============
3+
4+
5+
.. currentmodule:: {{ module }}
6+
7+
.. autoclass:: {{ objname }}
8+
9+
{% block methods %}
10+
.. automethod:: __init__
11+
.. automethod:: show
12+
.. automethod:: update_layout
13+
.. automethod:: add_traces
14+
{% endblock %}
15+
16+
Other methods
17+
{{ underline }}==============
18+
19+
.. autosummary::
20+
:toctree: generated/
21+
22+
plotly.graph_objects.{{ objname }}
23+
24+
25+
.. raw:: html
26+
27+
<div class="clearer"></div>

‎apidoc/_templates/function.rst

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
:mod:`{{module}}`.{{objname}}
2+
{{ underline }}====================
3+
4+
.. currentmodule:: {{ module }}
5+
6+
.. autofunction:: {{ objname }}
7+
8+
9+
.. raw:: html
10+
11+
<div class="clearer"></div>

‎apidoc/_templates/trace.rst

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
:mod:`{{module}}`.{{objname}}
2+
{{ underline }}
3+
4+
5+
.. currentmodule:: {{ module }}
6+
7+
.. autoclass:: {{ objname }}
8+
9+
{% block methods %}
10+
.. automethod:: __init__
11+
{% endblock %}
12+
13+
14+
:mod:`{{module}}`.{{objname.lower()}}
15+
{{ underline }}
16+
17+
.. autosummary::
18+
:toctree: generated/
19+
20+
plotly.graph_objects.{{ objname.lower() }}
21+
22+
.. automodule:: plotly.graph_objects.{{ objname.lower() }}
23+
:members:
24+
25+
26+
.. raw:: html
27+
28+
<div class="clearer"></div>

‎apidoc/conf.py

Lines changed: 203 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,203 @@
1+
# -*- coding: utf-8 -*-
2+
#
3+
# Configuration file for the Sphinx documentation builder.
4+
#
5+
# This file does only contain a selection of the most common options. For a
6+
# full list see the documentation:
7+
# http://www.sphinx-doc.org/en/master/config
8+
9+
# -- Path setup --------------------------------------------------------------
10+
11+
# If extensions (or modules to document with autodoc) are in another directory,
12+
# add these directories to sys.path here. If the directory is relative to the
13+
# documentation root, use os.path.abspath to make it absolute, like shown here.
14+
#
15+
import os
16+
import sys
17+
18+
# sys.path.insert(0, os.path.abspath("../packages/python/plotly"))
19+
20+
21+
# -- Project information -----------------------------------------------------
22+
23+
project = "plotly"
24+
copyright = "2019, plotly team"
25+
author = "plotly team"
26+
27+
# The short X.Y version
28+
version = ""
29+
# The full version, including alpha/beta/rc tags
30+
release = "4.2"
31+
32+
33+
# -- General configuration ---------------------------------------------------
34+
35+
# If your documentation needs a minimal Sphinx version, state it here.
36+
#
37+
# needs_sphinx = '1.0'
38+
39+
# Add any Sphinx extension module names here, as strings. They can be
40+
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
41+
# ones.
42+
extensions = [
43+
"sphinx.ext.autodoc",
44+
"sphinx.ext.autosummary",
45+
"sphinx.ext.intersphinx",
46+
"sphinx.ext.todo",
47+
"sphinx.ext.coverage",
48+
"sphinx.ext.napoleon",
49+
50+
]
51+
52+
autosummary_generate = True
53+
54+
# Add any paths that contain templates here, relative to this directory.
55+
templates_path = ['_templates']
56+
57+
58+
# The suffix(es) of source filenames.
59+
# You can specify multiple suffix as a list of string:
60+
#
61+
source_suffix = [".rst", ".md"]
62+
# source_suffix = '.rst'
63+
64+
source_parsers = {".md": "recommonmark.parser.CommonMarkParser"}
65+
# The master toctree document.
66+
master_doc = "index"
67+
68+
# The language for content autogenerated by Sphinx. Refer to documentation
69+
# for a list of supported languages.
70+
#
71+
# This is also used if you do content translation via gettext catalogs.
72+
# Usually you set "language" from the command line for these cases.
73+
language = None
74+
75+
# List of patterns, relative to source directory, that match files and
76+
# directories to ignore when looking for source files.
77+
# This pattern also affects html_static_path and html_extra_path.
78+
exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
79+
80+
# The name of the Pygments (syntax highlighting) style to use.
81+
pygments_style = None
82+
83+
84+
# -- Options for HTML output -------------------------------------------------
85+
86+
# The theme to use for HTML and HTML Help pages. See the documentation for
87+
# a list of builtin themes.
88+
#
89+
html_theme = "alabaster"
90+
91+
# Theme options are theme-specific and customize the look and feel of a theme
92+
# further. For a list of options available for each theme, see the
93+
# documentation.
94+
#
95+
html_theme_options = {
96+
#'nosidebar': True,
97+
'analytics_id':'UA-39373211-1',
98+
'logo':'logo.png',
99+
'page_width': '70%',
100+
'sidebar_width':'15%'
101+
}
102+
103+
# Add any paths that contain custom static files (such as style sheets) here,
104+
# relative to this directory. They are copied after the builtin static files,
105+
# so a file named "default.css" will overwrite the builtin "default.css".
106+
html_static_path = ["_static"]
107+
108+
# Custom sidebar templates, must be a dictionary that maps document names
109+
# to template names.
110+
#
111+
# The default sidebars (for documents that don't match any pattern) are
112+
# defined by theme itself. Builtin themes are using these templates by
113+
# default: ``['localtoc.html', 'relations.html', 'sourcelink.html',
114+
# 'searchbox.html']``.
115+
#
116+
# html_sidebars = {}
117+
118+
119+
# -- Options for HTMLHelp output ---------------------------------------------
120+
121+
# Output file base name for HTML help builder.
122+
htmlhelp_basename = "plotlydoc"
123+
124+
125+
# -- Options for LaTeX output ------------------------------------------------
126+
127+
latex_elements = {
128+
# The paper size ('letterpaper' or 'a4paper').
129+
#
130+
# 'papersize': 'letterpaper',
131+
# The font size ('10pt', '11pt' or '12pt').
132+
#
133+
# 'pointsize': '10pt',
134+
# Additional stuff for the LaTeX preamble.
135+
#
136+
# 'preamble': '',
137+
# Latex figure (float) alignment
138+
#
139+
# 'figure_align': 'htbp',
140+
}
141+
142+
# Grouping the document tree into LaTeX files. List of tuples
143+
# (source start file, target name, title,
144+
# author, documentclass [howto, manual, or own class]).
145+
latex_documents = [
146+
(master_doc, "plotly.tex", "plotly Documentation", "plotly team", "manual")
147+
]
148+
149+
150+
# -- Options for manual page output ------------------------------------------
151+
152+
# One entry per manual page. List of tuples
153+
# (source start file, name, description, authors, manual section).
154+
man_pages = [(master_doc, "plotly", "plotly Documentation", [author], 1)]
155+
156+
157+
# -- Options for Texinfo output ----------------------------------------------
158+
159+
# Grouping the document tree into Texinfo files. List of tuples
160+
# (source start file, target name, title, author,
161+
# dir menu entry, description, category)
162+
texinfo_documents = [
163+
(
164+
master_doc,
165+
"plotly",
166+
"plotly Documentation",
167+
author,
168+
"plotly",
169+
"One line description of project.",
170+
"Miscellaneous",
171+
)
172+
]
173+
174+
175+
# -- Options for Epub output -------------------------------------------------
176+
177+
# Bibliographic Dublin Core info.
178+
epub_title = project
179+
180+
# The unique identifier of the text. This can be a ISBN number
181+
# or the project homepage.
182+
#
183+
# epub_identifier = ''
184+
185+
# A unique identification for the text.
186+
#
187+
# epub_uid = ''
188+
189+
# A list of files that should not be packed into the epub file.
190+
epub_exclude_files = ["search.html"]
191+
192+
193+
# -- Extension configuration -------------------------------------------------
194+
195+
# -- Options for intersphinx extension ---------------------------------------
196+
197+
# Example configuration for intersphinx: refer to the Python standard library.
198+
intersphinx_mapping = {"https://docs.python.org/": None}
199+
200+
# -- Options for todo extension ----------------------------------------------
201+
202+
# If true, `todo` and `todoList` produce output, else they produce nothing.
203+
todo_include_todos = True

‎apidoc/figure.rst

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
Figure
2+
======
3+
4+
.. currentmodule:: plotly.graph_objects
5+
6+
.. autosummary::
7+
:toctree: generated/
8+
9+
Figure
10+
11+
Figure.show
12+
Figure.update_layout
13+
Figure.add_traces
14+
15+
16+
.. autoclass:: Figure
17+
:members:

‎apidoc/figure_factory.rst

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
.. _ff:
2+
3+
Figure Factory
4+
==============
5+
6+
.. currentmodule:: plotly.figure_factory
7+
8+
.. autosummary::
9+
:toctree: generated/
10+
:template: function.rst
11+
12+
create_2d_density
13+
create_annotated_heatmap
14+
create_bullet
15+
create_candlestick
16+
create_dendrogram
17+
create_distplot
18+
create_facet_grid
19+
create_gantt
20+
create_ohlc
21+
create_quiver
22+
create_scatterplotmatrix
23+
create_streamline
24+
create_table
25+
create_ternary_contour
26+
create_trisurf
27+
create_violin
28+

0 commit comments

Comments
 (0)