Skip to content

Commit c3b77bc

Browse files
emmanuelleemmanuelle
authored
Doc migration: integrate tutorials and apidoc into main plotly.py repo (plotly#1936)
1 parent 93ec054 commit c3b77bc

File tree

226 files changed

+43912
-1601
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

226 files changed

+43912
-1601
lines changed

‎.circleci/config.yml

+107
Original file line numberDiff line numberDiff line change
@@ -385,6 +385,112 @@ jobs:
385385
- store_artifacts:
386386
path: packages/python/plotly/dist
387387

388+
389+
build-doc:
390+
resource_class: xlarge
391+
docker:
392+
# specify the version you desire here
393+
# use `-browsers` prefix for selenium tests, e.g. `3.6.1-browsers`
394+
- image: circleci/python:3.6.8-node
395+
396+
397+
working_directory: ~/project
398+
399+
steps:
400+
- add_ssh_keys:
401+
fingerprints:
402+
- "d9:b0:da:5c:3e:8c:b6:b6:d5:b6:35:70:ce:fe:f5:b1"
403+
404+
- checkout
405+
406+
# Download and cache dependencies
407+
- restore_cache:
408+
keys:
409+
- v1-dependencies-{{ checksum "doc/requirements.txt" }}
410+
# fallback to using the latest cache if no exact match is found
411+
- v1-dependencies-
412+
413+
- run:
414+
name: install dependencies
415+
command: |
416+
cd doc
417+
python3 -m venv venv
418+
. venv/bin/activate
419+
npm install [email protected]
420+
npm install orca
421+
pip install -r requirements.txt
422+
if [ "${CIRCLE_BRANCH}" == "master" ]; then
423+
pip uninstall plotly
424+
cd ../packages/python/plotly
425+
python3 setup.py install
426+
cd ../../../doc
427+
fi
428+
echo 'export PATH="/home/circleci/project/doc/node_modules/.bin:$PATH"' >> $BASH_ENV
429+
sudo apt-get install -y poppler-utils libxtst6 xvfb libgtk2.0-0 libgconf-2-4 libnss3 libasound2
430+
cd ..
431+
432+
- save_cache:
433+
paths:
434+
- ./doc/venv
435+
- ./doc/node_modules
436+
key: v1-dependencies-{{ checksum "doc/requirements.txt" }}
437+
438+
- run:
439+
name: make html
440+
command: |
441+
cd doc
442+
. venv/bin/activate
443+
echo ${mapbox_token} > python/.mapbox_token
444+
make -kj8 || make -kj8
445+
curl https://raw.githubusercontent.com/plotly/documentation/source-design-merge/front-matter-ci.py > front-matter-ci.py
446+
curl https://raw.githubusercontent.com/plotly/documentation/source-design-merge/check-or-enforce-order.py > check-or-enforce-order.py
447+
python front-matter-ci.py build/html
448+
python check-or-enforce-order.py build/html
449+
if [ "${CIRCLE_BRANCH}" == "doc-prod" ]; then
450+
cd build/html
451+
git init
452+
git config user.name nicolaskruchten
453+
git config user.email [email protected]
454+
git add *
455+
git commit -m build
456+
git push --force [email protected]:plotly/plotly.py.git master:built
457+
rm -rf .git
458+
cd ../..
459+
fi
460+
tar -zcf build/html.tgz build/html
461+
rm -rf build/html build/ipynb
462+
cd ..
463+
464+
- run:
465+
name: make doc
466+
command: |
467+
cd doc
468+
. venv/bin/activate
469+
cd apidoc
470+
make html
471+
if [ "${CIRCLE_BRANCH}" == "doc-prod" ]; then
472+
cd _build/html
473+
touch .nojekyll
474+
git init
475+
git config user.name emmanuelle
476+
git config user.email [email protected]
477+
git add *
478+
git add .nojekyll
479+
git commit -m build
480+
git push --force [email protected]:plotly/plotly.py-docs.git master:gh-pages
481+
rm -rf .git
482+
cd ../..
483+
fi
484+
485+
cd ../..
486+
487+
488+
- store_artifacts:
489+
path: doc/build
490+
destination: doc/build
491+
492+
493+
388494
workflows:
389495
version: 2
390496
code_formatting:
@@ -413,3 +519,4 @@ workflows:
413519
- python-2-7-orca
414520
- python-3-5-orca
415521
- python-3-7-orca
522+
- build-doc

‎doc/Makefile

+58
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
2+
export PLOTLY_RENDERER=notebook_connected
3+
4+
MD_DIR ?= python
5+
UNCONV_DIR ?= unconverted/python
6+
IPYNB_DIR ?= build/ipynb
7+
HTML_DIR ?= build/html
8+
FAIL_DIR ?= build/failures
9+
REDIR_DIR ?= build/html/redir
10+
11+
MD_FILES := $(shell ls $(MD_DIR)/*.md)
12+
UNCONV_FILES := $(shell ls $(UNCONV_DIR)/*.md)
13+
14+
IPYNB_FILES := $(patsubst $(MD_DIR)/%.md,$(IPYNB_DIR)/%.ipynb,$(MD_FILES))
15+
HTML_FILES := $(patsubst $(MD_DIR)/%.md,$(HTML_DIR)/2019-07-03-%.html,$(MD_FILES))
16+
NEXT_REDIR_FILES := $(patsubst $(MD_DIR)/%.md,$(REDIR_DIR)/2019-07-03-redirect-next-%.html,$(MD_FILES))
17+
V3_REDIR_FILES := $(patsubst $(UNCONV_DIR)/%.md,$(REDIR_DIR)/2019-07-03-redirect-v3-%.html,$(UNCONV_FILES))
18+
19+
20+
all: $(HTML_FILES) $(V3_REDIR_FILES) $(NEXT_REDIR_FILES)
21+
22+
.PRECIOUS: $(IPYNB_FILES)
23+
24+
$(IPYNB_DIR)/.mapbox_token: $(MD_DIR)/.mapbox_token
25+
@mkdir -p $(IPYNB_DIR)
26+
cd $(IPYNB_DIR) && ln -s ../../$<
27+
28+
$(IPYNB_FILES): $(IPYNB_DIR)/.mapbox_token
29+
30+
$(IPYNB_DIR)/%.ipynb: $(MD_DIR)/%.md
31+
@mkdir -p $(IPYNB_DIR)
32+
@echo "[jupytext] $<"
33+
@jupytext $< --to notebook --quiet --output $@
34+
35+
$(HTML_DIR)/2019-07-03-%.html: $(IPYNB_DIR)/%.ipynb
36+
@mkdir -p $(HTML_DIR)
37+
@mkdir -p $(FAIL_DIR)
38+
@echo "[nbconvert] $<"
39+
@jupyter nbconvert $< --to html --template nb.tpl \
40+
--output-dir $(HTML_DIR) --output 2019-07-03-$*.html \
41+
--execute
42+
43+
44+
$(REDIR_DIR)/2019-07-03-redirect-next-%.html: $(IPYNB_DIR)/%.ipynb
45+
@mkdir -p $(REDIR_DIR)
46+
@echo "[next-redir] $<"
47+
@jupyter nbconvert $< --to html --template next_redirect.tpl \
48+
--output-dir $(REDIR_DIR) --output 2019-07-03-redirect-next-$*.html
49+
50+
51+
$(REDIR_DIR)/2019-07-03-redirect-v3-%.html: $(UNCONV_DIR)/%.md
52+
@mkdir -p $(REDIR_DIR)
53+
@echo "[v3-redir] $<"
54+
@echo "---" > $(REDIR_DIR)/2019-07-03-redirect-v3-$*.html
55+
@echo "permalink: python/$*/" >> $(REDIR_DIR)/2019-07-03-redirect-v3-$*.html
56+
@echo "redirect_to: https://plot.ly/python/v3/$*/" >> $(REDIR_DIR)/2019-07-03-redirect-v3-$*.html
57+
@echo "sitemap: true" >> $(REDIR_DIR)/2019-07-03-redirect-v3-$*.html
58+
@echo "---" >> $(REDIR_DIR)/2019-07-03-redirect-v3-$*.html

‎doc/README.md

+5
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
# plotly.py-docs
2+
3+
Documentation repo for plotly.py v4
4+
5+
The output of the `Makefile` is stored by CI in the `built` branch which is then used by the `documentation` repo to generate https://plot.ly/python

‎doc/apidoc/Makefile

+19
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)

‎doc/apidoc/README.rst

+1
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
make html

‎doc/apidoc/_static/favicon.ico

4.19 KB
Binary file not shown.

‎doc/apidoc/_static/logo.png

6.56 KB
Loading

‎doc/apidoc/_static/plotly-style.css

+38
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
.navbar-default {
2+
background-color: #00004f;
3+
}
4+
.navbar {
5+
min-height: 75px;
6+
}
7+
.navbar-brand {
8+
font-family: "Open Sans", sans-serif;
9+
padding: 10px 10px;
10+
}
11+
.body {
12+
font-family: "Open Sans", sans-serif;
13+
}
14+
.navbar-brand img {
15+
height: 30px;
16+
margin-top: 4px;
17+
}
18+
19+
.navbar .container {
20+
padding-top: 8px;
21+
}
22+
23+
a {
24+
color: #2391fe !important;
25+
}
26+
27+
code {
28+
color: #2c3e50 !important;
29+
}
30+
31+
.alert-info {
32+
background: lightgrey;
33+
}
34+
35+
36+
.dropdown-menu>li>a:hover, .dropdown-menu>li>a:focus {
37+
background: lightgrey;
38+
}

‎doc/apidoc/_templates/class.rst

+15
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>

‎doc/apidoc/_templates/class_figure.rst

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

‎doc/apidoc/_templates/function.rst

+11
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>

‎doc/apidoc/_templates/layout.html

+21
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
{# Import the theme's layout. #}
2+
{% extends "!layout.html" %}
3+
4+
{%- block footer %}
5+
<script type="text/javascript">
6+
7+
var _gaq = _gaq || [];
8+
_gaq.push(['_setAccount', 'UA-39373211-1']);
9+
_gaq.push(['_setDomainName', 'none']);
10+
_gaq.push(['_setAllowLinker', true]);
11+
_gaq.push(['_trackPageview']);
12+
13+
(function() {
14+
var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
15+
ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
16+
var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
17+
})();
18+
19+
</script>
20+
{%- endblock %}
21+

‎doc/apidoc/_templates/trace.rst

+27
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+
{% endblock %}
12+
13+
14+
:mod:`{{module}}`.{{objname.lower()}}
15+
{{ underline }}================================
16+
17+
.. autosummary::
18+
19+
plotly.graph_objects.{{ objname.lower() }}
20+
21+
.. automodule:: plotly.graph_objects.{{ objname.lower() }}
22+
:members:
23+
24+
25+
.. raw:: html
26+
27+
<div class="clearer"></div>

‎doc/apidoc/basefigure.rst

+9
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
.. _base:
2+
3+
.. currentmodule:: plotly.basedatatypes
4+
5+
.. autosummary::
6+
:toctree: generated/
7+
8+
BaseFigure
9+

0 commit comments

Comments
 (0)