Skip to content

Commit fbb05b9

Browse files
author
Mark Gibbs
committed
Raw documentation files
1 parent 293b454 commit fbb05b9

File tree

7 files changed

+258
-6
lines changed

7 files changed

+258
-6
lines changed

‎README.md‎

Lines changed: 94 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3,8 +3,100 @@
33
Expose [plotly dash](https://plot.ly/products/dash/) apps as django tags.
44

55
See the source for this project here:
6-
<https://github.com/GibbsConsulting/django-plotly-dash>.
6+
<https://github.com/GibbsConsulting/django-plotly-dash>
7+
8+
Online documentation can be found here:
9+
<https://readthedocs.org/projects/django-plotly-dash>
710

811
## Installation
912

10-
To use existing dash applications, just register thenm
13+
First, install the package. This will also install plotly and some dash packages if they are not already present.
14+
15+
pip install django_plotly_dash
16+
17+
Then, just add `django_plotly_dash` to `INSTALLED_APPS` in your Django `settings.py` file
18+
19+
INSTALLED_APPS = [
20+
...
21+
'django_plotly_dash',
22+
...
23+
]
24+
25+
## Demonstration
26+
27+
The source repository contains a demo application. To clone the repo and lauch the demo:
28+
29+
```bash
30+
git clone https://github.com/GibbsConsulting/django-plotly-dash.git
31+
32+
cd django-plotly-dash
33+
34+
./make_env # sets up a virtual environment for development
35+
# with direct use of the source code for the package
36+
37+
./prepare_demo # prepares and launches the demo
38+
# using the Django debug server at http://localhost:8000
39+
```
40+
41+
## Usage
42+
43+
To use existing dash applications, first register them using the `DelayedDash` class. This
44+
replaces the `dash.Dash` class of `plotly.py.`
45+
46+
Taking as an example a slightly modified variant of one of the [getting started](https://dash.plot.ly/getting-started-part-2) examples:
47+
48+
```python
49+
import dash
50+
import dash_core_components as dcc
51+
import dash_html_components as html
52+
53+
from django_plotly_dash import DelayedDash
54+
55+
app = DelayedDash('SimpleExample') # replaces dash.Dash
56+
57+
app.layout = html.Div([
58+
dcc.RadioItems(
59+
id='dropdown-a',
60+
options=[{'label': i, 'value': i} for i in ['Canada', 'USA', 'Mexico']],
61+
value='Canada'
62+
),
63+
html.Div(id='output-a'),
64+
65+
dcc.RadioItems(
66+
id='dropdown-b',
67+
options=[{'label': i, 'value': i} for i in ['MTL', 'NYC', 'SF']],
68+
value='MTL'
69+
),
70+
html.Div(id='output-b')
71+
72+
])
73+
74+
@app.callback(
75+
dash.dependencies.Output('output-a', 'children'),
76+
[dash.dependencies.Input('dropdown-a', 'value')])
77+
def callback_a(dropdown_value):
78+
return 'You\'ve selected "{}"'.format(dropdown_value)
79+
80+
81+
@app.callback(
82+
dash.dependencies.Output('output-b', 'children'),
83+
[dash.dependencies.Input('dropdown-a', 'value'),
84+
dash.dependencies.Input('dropdown-b', 'value')])
85+
def callback_b(dropdown_value,other_dd):
86+
return 'You\'ve selected "{}" and "{}"'.format(dropdown_value,
87+
other_dd)
88+
```
89+
90+
Note that the `DelayedDash` constructor requires a name to be specified. This name is then used to identify the dash app in
91+
templates:
92+
93+
```jinja2
94+
{% load plotly_dash %}
95+
96+
{% plotly_item "SimpleExample" %}
97+
```
98+
99+
Note that the registration code needs to be in a location
100+
that will be imported into the Django process before any template tag attempts to use it. The example Django application
101+
in the demo subdirectory achieves this through an import in the main urls.py file; any views.py would also be sufficient.
102+

‎dev_requirements.txt‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
alabaster==0.7.10
2+
argh==0.26.2
3+
Babel==2.5.3
4+
certifi==2018.4.16
5+
chardet==3.0.4
6+
click==6.7
7+
dash==0.21.1
8+
dash-core-components==0.22.1
9+
dash-html-components==0.10.1
10+
dash-renderer==0.12.1
11+
decorator==4.3.0
12+
Django==2.0.5
13+
-e git+https://github.com/delsim/django-plotly-dash.git@293b454ee8965422155a971d9e417878dc89ce82#egg=django_plotly_dash
14+
docopt==0.6.2
15+
docutils==0.14
16+
Flask==1.0.2
17+
Flask-Compress==1.4.0
18+
grip==4.5.2
19+
idna==2.6
20+
imagesize==1.0.0
21+
ipython-genutils==0.2.0
22+
itsdangerous==0.24
23+
Jinja2==2.10
24+
jsonschema==2.6.0
25+
jupyter-core==4.4.0
26+
livereload==2.5.2
27+
Markdown==2.6.11
28+
MarkupSafe==1.0
29+
nbformat==4.4.0
30+
packaging==17.1
31+
path-and-address==2.0.1
32+
pathtools==0.1.2
33+
pkginfo==1.4.2
34+
plotly==2.5.1
35+
port-for==0.3.1
36+
Pygments==2.2.0
37+
pyparsing==2.2.0
38+
pytz==2018.4
39+
PyYAML==3.12
40+
requests==2.18.4
41+
requests-toolbelt==0.8.0
42+
six==1.11.0
43+
snowballstemmer==1.2.1
44+
Sphinx==1.7.4
45+
sphinx-autobuild==0.7.1
46+
sphinx-rtd-theme==0.3.1
47+
sphinxcontrib-websupport==1.0.1
48+
tornado==5.0.2
49+
tqdm==4.23.3
50+
traitlets==4.3.2
51+
twine==1.11.0
52+
urllib3==1.22
53+
watchdog==0.8.3
54+
Werkzeug==0.14.1

‎docs/conf.py‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,7 @@
2020
# -- Project information -----------------------------------------------------
2121

2222
project = 'django-plotly-dash'
23-
copyright = '2018, Mark Gibbs'
23+
copyright = '2018 Gibbs Consulting, a division of 0802100 (BC) Ltd'
2424
author = 'Mark Gibbs'
2525

2626
# The short X.Y version
@@ -74,7 +74,8 @@
7474
# The theme to use for HTML and HTML Help pages. See the documentation for
7575
# a list of builtin themes.
7676
#
77-
html_theme = 'alabaster'
77+
#html_theme = 'alabaster'
78+
html_theme = 'sphinx_rtd_theme'
7879

7980
# Theme options are theme-specific and customize the look and feel of a theme
8081
# further. For a list of options available for each theme, see the
@@ -152,4 +153,4 @@
152153
(master_doc, 'django-plotly-dash', 'django-plotly-dash Documentation',
153154
author, 'django-plotly-dash', 'One line description of project.',
154155
'Miscellaneous'),
155-
]
156+
]

‎docs/index.rst‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,14 +6,19 @@
66
Welcome to django-plotly-dash's documentation!
77
==============================================
88

9+
Contents
10+
--------
11+
912
.. toctree::
1013
:maxdepth: 2
1114
:caption: Contents:
1215

16+
installation
17+
simple_use
1318

1419

1520
Indices and tables
16-
==================
21+
------------------
1722

1823
* :ref:`genindex`
1924
* :ref:`modindex`

‎docs/installation.rst‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
.. _installation:
2+
3+
Installation
4+
============
5+
6+
Use pip to install the package, preferably to a local virtualenv.::
7+
8+
pip install django_plotly_dash
9+
10+
Then, add ``django_plotly_dash`` to ``INSTALLED_APPS`` in the Django settings.py file::
11+
12+
INSTALLED_APPS = [
13+
...
14+
'django_plotly_dash',
15+
...
16+
]
17+
18+
The plotly_item tag in the plotly_dash tag library can then be used to render any registered dash component. See :ref:`simple_use` for a simple example.
19+
20+
Source code and demo
21+
--------------------
22+
23+
The source code repository contains a simple demo application.
24+
25+
To install and run it::
26+
27+
git clone https://github.com/GibbsConsulting/django-plotly-dash.git
28+
29+
cd django-plotly-dash
30+
31+
./make_env # sets up a virtual environment
32+
# with direct use of the source
33+
# code for the package
34+
35+
./prepare_demo # prepares and launches the demo
36+
# using the Django debug server
37+
# at http://localhost:8000
38+

‎docs/simple_use.rst‎

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
.. _simple_use:
2+
3+
Simple Usage
4+
============
5+
6+
To use existing dash applications, first register them using the ``DelayedDash`` class. This
7+
replaces the ``dash.Dash`` class of ``plotly.py``
8+
9+
Taking as an example a slightly modified variant of one of the `getting started <https://dash.plot.ly/getting-started-part-2>`_ examples::
10+
11+
import dash
12+
import dash_core_components as dcc
13+
import dash_html_components as html
14+
15+
from django_plotly_dash import DelayedDash
16+
17+
app = DelayedDash('SimpleExample') # replaces dash.Dash
18+
19+
app.layout = html.Div([
20+
dcc.RadioItems(
21+
id='dropdown-a',
22+
options=[{'label': i, 'value': i} for i in ['Canada', 'USA', 'Mexico']],
23+
value='Canada'
24+
),
25+
html.Div(id='output-a'),
26+
27+
dcc.RadioItems(
28+
id='dropdown-b',
29+
options=[{'label': i, 'value': i} for i in ['MTL', 'NYC', 'SF']],
30+
value='MTL'
31+
),
32+
html.Div(id='output-b')
33+
34+
])
35+
36+
@app.callback(
37+
dash.dependencies.Output('output-a', 'children'),
38+
[dash.dependencies.Input('dropdown-a', 'value')])
39+
def callback_a(dropdown_value):
40+
return 'You\'ve selected "{}"'.format(dropdown_value)
41+
42+
43+
@app.callback(
44+
dash.dependencies.Output('output-b', 'children'),
45+
[dash.dependencies.Input('dropdown-a', 'value'),
46+
dash.dependencies.Input('dropdown-b', 'value')])
47+
def callback_b(dropdown_value,other_dd):
48+
return 'You\'ve selected "{}" and "{}"'.format(dropdown_value,
49+
other_dd)
50+
51+
Note that the ``DelayedDash`` constructor requires a name to be specified. This name is then used to identify the dash app in
52+
templates:::
53+
54+
{%load plotly_dash%}
55+
56+
{%plotly_item "SimpleExample"%}
57+
58+
Note that the registration code needs to be in a location
59+
that will be imported into the Django process before any template tag attempts to use it. The example Django application
60+
in the demo subdirectory achieves this through an import in the main urls.py file; any views.py would also be sufficient.
61+

‎setup.py‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -32,6 +32,7 @@
3232
project_urls = {
3333
'Source': "https://github.com/GibbsConsulting/django-plotly-dash",
3434
'Tracker': "https://github.com/GibbsConsulting/django-plotly-dash/issues",
35+
'Documentation': 'http://django-plotly-dash.readthedocs.io/',
3536
},
3637
install_requires = ['plotly',
3738
'dash',

0 commit comments

Comments
 (0)