Skip to content

Commit f2ca319

Browse files
delsimGibbsConsulting
delsim
authored and
GibbsConsulting
committed
Documentation skeleton (#2)
* Initial files * Added demo app * First working demo example. Need to relocate demo template * Fix up requirements.txt file. Removal of spurious entry * Update setup and related scripts * Rename template tag * Relocate demo template inside demo, not app * Adding skeleton for documentation * Raw documentation files
1 parent 466b71a commit f2ca319

File tree

12 files changed

+485
-24
lines changed

12 files changed

+485
-24
lines changed

‎README.md‎

Lines changed: 97 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,102 @@
11
# django-plotly-dash
22

3-
Expose plotly dash apps as django tags.
3+
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>
10+
11+
## Installation
12+
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.
7102

‎demo/demo/settings.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -56,7 +56,7 @@
5656
TEMPLATES = [
5757
{
5858
'BACKEND': 'django.template.backends.django.DjangoTemplates',
59-
'DIRS': [],
59+
'DIRS': [os.path.join(BASE_DIR,'demo','templates'),],
6060
'APP_DIRS': True,
6161
'OPTIONS': {
6262
'context_processors': [

‎demo/demo/templates/index.html‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
<!DOCTYPE HTML>
2+
<html>
3+
{%load plotly_dash%}
4+
<title>Simple stuff</title>
5+
<body>
6+
<div>
7+
Content here
8+
{%plotly_item "SimpleExample"%}
9+
</div>
10+
<div>
11+
Content here
12+
{%plotly_item "SimpleExample"%}
13+
</div>
14+
<div>
15+
Content here
16+
{%plotly_item "Ex2"%}
17+
</div>
18+
</body>
19+
</html>

‎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

‎django_plotly_dash/templatetags/plotly_dash.py‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
from django import template
2+
3+
register = template.Library()
4+
5+
from django_plotly_dash.dash_wrapper import get_app_by_name
6+
7+
@register.inclusion_tag("django_plotly_dash/plotly_item.html", takes_context=True)
8+
def plotly_item(context, app_name):
9+
10+
app = get_app_by_name(app_name)
11+
url = app.base_url()
12+
13+
return locals()

‎docs/Makefile‎

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

‎docs/conf.py‎

Lines changed: 156 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,156 @@
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+
# sys.path.insert(0, os.path.abspath('.'))
18+
19+
20+
# -- Project information -----------------------------------------------------
21+
22+
project = 'django-plotly-dash'
23+
copyright = '2018 Gibbs Consulting, a division of 0802100 (BC) Ltd'
24+
author = 'Mark Gibbs'
25+
26+
# The short X.Y version
27+
version = ''
28+
# The full version, including alpha/beta/rc tags
29+
release = ''
30+
31+
32+
# -- General configuration ---------------------------------------------------
33+
34+
# If your documentation needs a minimal Sphinx version, state it here.
35+
#
36+
# needs_sphinx = '1.0'
37+
38+
# Add any Sphinx extension module names here, as strings. They can be
39+
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
40+
# ones.
41+
extensions = [
42+
]
43+
44+
# Add any paths that contain templates here, relative to this directory.
45+
templates_path = ['_templates']
46+
47+
# The suffix(es) of source filenames.
48+
# You can specify multiple suffix as a list of string:
49+
#
50+
# source_suffix = ['.rst', '.md']
51+
source_suffix = '.rst'
52+
53+
# The master toctree document.
54+
master_doc = 'index'
55+
56+
# The language for content autogenerated by Sphinx. Refer to documentation
57+
# for a list of supported languages.
58+
#
59+
# This is also used if you do content translation via gettext catalogs.
60+
# Usually you set "language" from the command line for these cases.
61+
language = None
62+
63+
# List of patterns, relative to source directory, that match files and
64+
# directories to ignore when looking for source files.
65+
# This pattern also affects html_static_path and html_extra_path .
66+
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
67+
68+
# The name of the Pygments (syntax highlighting) style to use.
69+
pygments_style = 'sphinx'
70+
71+
72+
# -- Options for HTML output -------------------------------------------------
73+
74+
# The theme to use for HTML and HTML Help pages. See the documentation for
75+
# a list of builtin themes.
76+
#
77+
#html_theme = 'alabaster'
78+
html_theme = 'sphinx_rtd_theme'
79+
80+
# Theme options are theme-specific and customize the look and feel of a theme
81+
# further. For a list of options available for each theme, see the
82+
# documentation.
83+
#
84+
# html_theme_options = {}
85+
86+
# Add any paths that contain custom static files (such as style sheets) here,
87+
# relative to this directory. They are copied after the builtin static files,
88+
# so a file named "default.css" will overwrite the builtin "default.css".
89+
html_static_path = ['_static']
90+
91+
# Custom sidebar templates, must be a dictionary that maps document names
92+
# to template names.
93+
#
94+
# The default sidebars (for documents that don't match any pattern) are
95+
# defined by theme itself. Builtin themes are using these templates by
96+
# default: ``['localtoc.html', 'relations.html', 'sourcelink.html',
97+
# 'searchbox.html']``.
98+
#
99+
# html_sidebars = {}
100+
101+
102+
# -- Options for HTMLHelp output ---------------------------------------------
103+
104+
# Output file base name for HTML help builder.
105+
htmlhelp_basename = 'django-plotly-dashdoc'
106+
107+
108+
# -- Options for LaTeX output ------------------------------------------------
109+
110+
latex_elements = {
111+
# The paper size ('letterpaper' or 'a4paper').
112+
#
113+
# 'papersize': 'letterpaper',
114+
115+
# The font size ('10pt', '11pt' or '12pt').
116+
#
117+
# 'pointsize': '10pt',
118+
119+
# Additional stuff for the LaTeX preamble.
120+
#
121+
# 'preamble': '',
122+
123+
# Latex figure (float) alignment
124+
#
125+
# 'figure_align': 'htbp',
126+
}
127+
128+
# Grouping the document tree into LaTeX files. List of tuples
129+
# (source start file, target name, title,
130+
# author, documentclass [howto, manual, or own class]).
131+
latex_documents = [
132+
(master_doc, 'django-plotly-dash.tex', 'django-plotly-dash Documentation',
133+
'Mark Gibbs', 'manual'),
134+
]
135+
136+
137+
# -- Options for manual page output ------------------------------------------
138+
139+
# One entry per manual page. List of tuples
140+
# (source start file, name, description, authors, manual section).
141+
man_pages = [
142+
(master_doc, 'django-plotly-dash', 'django-plotly-dash Documentation',
143+
[author], 1)
144+
]
145+
146+
147+
# -- Options for Texinfo output ----------------------------------------------
148+
149+
# Grouping the document tree into Texinfo files. List of tuples
150+
# (source start file, target name, title, author,
151+
# dir menu entry, description, category)
152+
texinfo_documents = [
153+
(master_doc, 'django-plotly-dash', 'django-plotly-dash Documentation',
154+
author, 'django-plotly-dash', 'One line description of project.',
155+
'Miscellaneous'),
156+
]

0 commit comments

Comments
 (0)