re-add 'validate eventName' TODO.
[dygraphs.git] / generate-documentation.py
CommitLineData
db071c3e 1#!/usr/bin/env python
ea910bfa
RK
2
3# Generate docs/options.html
4
0e37f8e5
DV
5import json
6import glob
7import re
d1d19c3e
DV
8import sys
9
10# Set this to the path to a test file to get debug output for just that test
11# file. Can be helpful to figure out why a test is not being shown for a
12# particular option.
13debug_tests = [] # [ 'tests/zoom.html' ]
0e37f8e5 14
88b1e052 15# Pull options reference JSON out of dygraph.js
0e37f8e5
DV
16js = ''
17in_json = False
730852d8 18for line in file('dygraph-options-reference.js'):
0e37f8e5
DV
19 if '<JSON>' in line:
20 in_json = True
21 elif '</JSON>' in line:
22 in_json = False
23 elif in_json:
24 js += line
25
26# TODO(danvk): better errors here.
27assert js
28docs = json.loads(js)
29
30# Go through the tests and find uses of each option.
31for opt in docs:
32 docs[opt]['tests'] = []
473278ec 33 docs[opt]['gallery'] = []
0e37f8e5 34
88b1e052
DV
35# This is helpful for differentiating uses of options like 'width' and 'height'
36# from appearances of identically-named options in CSS.
0e37f8e5
DV
37def find_braces(txt):
38 """Really primitive method to find text inside of {..} braces.
39 Doesn't work if there's an unmatched brace in a string, e.g. '{'. """
40 out = ''
41 level = 0
42 for char in txt:
43 if char == '{':
44 level += 1
45 if level >= 1:
46 out += char
47 if char == '}':
48 level -= 1
49 return out
50
473278ec
RK
51def search_files(type, files):
52 # Find text followed by a colon. These won't all be options, but those that
53 # have the same name as a Dygraph option probably will be.
54 prop_re = re.compile(r'\b([a-zA-Z0-9]+) *:')
55 for test_file in files:
11c49f0e
RK
56 text = file(test_file).read()
57 # Hack for slipping past gallery demos that have title in their attributes
58 # so they don't appear as reasons for the demo to have 'title' options.
59 if type == "gallery":
60 idx = text.find("function(")
61 if idx >= 0:
62 text = text[idx:]
63 braced_html = find_braces(text)
473278ec
RK
64 if debug_tests:
65 print braced_html
66
67 ms = re.findall(prop_re, braced_html)
68 for opt in ms:
69 if debug_tests: print '\n'.join(ms)
70 if opt in docs and test_file not in docs[opt][type]:
71 docs[opt][type].append(test_file)
72
73search_files("tests", glob.glob("tests/*.html"))
74search_files("gallery", glob.glob("gallery/*.js")) #TODO add grep "Gallery.register\("
0e37f8e5 75
d1d19c3e
DV
76if debug_tests: sys.exit(0)
77
a38e9336
DV
78# Extract a labels list.
79labels = []
80for nu, opt in docs.iteritems():
81 for label in opt['labels']:
82 if label not in labels:
83 labels.append(label)
84
b5bdd85b 85print """<!DOCTYPE HTML>
a38e9336
DV
86<html>
87<head>
88 <title>Dygraphs Options Reference</title>
5af2de24 89 <link rel="stylesheet" href="style.css">
a38e9336
DV
90 <style type="text/css">
91 p.option {
92 padding-left: 25px;
5af2de24 93 }
b5bdd85b
RK
94 div.parameters {
95 padding-left: 15px;
96 }
5af2de24
DV
97 #nav {
98 position: fixed;
99 }
100 #content {
a38e9336
DV
101 max-width: 800px;
102 }
103 </style>
104</head>
105<body>
106"""
107
5af2de24 108print """
b5bdd85b 109<div id='nav'>
5af2de24
DV
110<h2>Dygraphs</h2>
111<ul>
112 <li><a href="index.html">Home</a>
113 <li><a href="data.html">Data Formats</a></li>
114 <li><a href="annotations.html">Annotations</a></li>
115</ul>
116<h2>Options Reference</h2>
117<ul>
118 <li><a href="#usage">Usage</a>
119"""
a38e9336
DV
120for label in sorted(labels):
121 print ' <li><a href="#%s">%s</a>\n' % (label, label)
5af2de24 122print '</ul>\n</div>\n\n'
a38e9336 123
5af2de24 124print """
b5bdd85b 125<div id='content'>
5af2de24
DV
126<h2>Options Reference</h2>
127<p>Dygraphs tries to do a good job of displaying your data without any further configuration. But inevitably, you're going to want to tinker. Dygraphs provides a rich set of options for configuring its display and behavior.</p>
128
b5bdd85b
RK
129<a name="usage"></a><h3>Usage</h3>
130<p>You specify options in the third parameter to the dygraphs constructor:</p>
5af2de24
DV
131<pre>g = new Dygraph(div,
132 data,
133 {
134 option1: value1,
135 option2: value2,
136 ...
137 });
138</pre>
139
b5bdd85b 140<p>After you've created a Dygraph, you can change an option by calling the <code>updateOptions</code> method:</p>
5af2de24
DV
141<pre>g.updateOptions({
142 new_option1: value1,
143 new_option2: value2
144 });
145</pre>
5af2de24
DV
146<p>And, without further ado, here's the complete list of options:</p>
147"""
473278ec 148
0295cce3 149def test_name(f):
473278ec
RK
150 """Takes 'tests/demo.html' -> 'demo'"""
151 return f.replace('tests/', '').replace('.html', '')
152
0295cce3 153def gallery_name(f):
473278ec
RK
154 """Takes 'gallery/demo.js' -> 'demo'"""
155 return f.replace('gallery/', '').replace('.js', '')
156
157def urlify_gallery(f):
158 """Takes 'gallery/demo.js' -> 'demo'"""
159 return f.replace('gallery/', 'gallery/#g/').replace('.js', '')
160
161
a38e9336 162for label in sorted(labels):
5af2de24 163 print '<a name="%s"><h3>%s</h3>\n' % (label, label)
a38e9336
DV
164
165 for opt_name in sorted(docs.keys()):
166 opt = docs[opt_name]
167 if label not in opt['labels']: continue
168 tests = opt['tests']
169 if not tests:
170 examples_html = '<font color=red>NONE</font>'
171 else:
172 examples_html = ' '.join(
0295cce3 173 '<a href="%s">%s</a>' % (f, test_name(f)) for f in tests)
473278ec
RK
174
175 gallery = opt['gallery']
176 if not gallery:
177 gallery_html = '<font color=red>NONE</font>'
178 else:
179 gallery_html = ' '.join(
0295cce3 180 '<a href="%s">%s</a>' % (urlify_gallery(f), gallery_name(f)) for f in gallery)
a38e9336 181
b5bdd85b
RK
182 if 'parameters' in opt:
183 parameters = opt['parameters']
184 parameters_html = '\n'.join("<i>%s</i>: %s<br/>" % (p[0], p[1]) for p in parameters)
185 parameters_html = "\n <div class='parameters'>\n%s</div>" % (parameters_html);
186 else:
187 parameters_html = ''
188
5af2de24
DV
189 if not opt['type']: opt['type'] = '(missing)'
190 if not opt['default']: opt['default'] = '(missing)'
191 if not opt['description']: opt['description'] = '(missing)'
192
a38e9336 193 print """
b5bdd85b 194 <div class='option'><a name="%(name)s"></a><b>%(name)s</b><br/>
11c49f0e 195 <p>%(desc)s</p>
b5bdd85b 196 <i>Type: %(type)s</i><br/>%(parameters)s
11c49f0e 197 <i>Default: %(default)s</i></p>
2941da80
RK
198 Gallery Samples: %(gallery_html)s<br/>
199 Other Examples: %(examples_html)s<br/>
b5bdd85b 200 <br/></div>
a38e9336
DV
201 """ % { 'name': opt_name,
202 'type': opt['type'],
b5bdd85b 203 'parameters': parameters_html,
a38e9336
DV
204 'default': opt['default'],
205 'desc': opt['description'],
473278ec
RK
206 'examples_html': examples_html,
207 'gallery_html': gallery_html}
0e37f8e5 208
0e37f8e5 209
5af2de24 210print """
b5bdd85b
RK
211<a name="point_properties"></a><h3>Point Properties</h3>
212Some callbacks take a point argument. Its properties are:<br/>
213<ul>
214<li>xval/yval: The data coordinates of the point (with dates/times as millis since epoch)</li>
215<li>canvasx/canvasy: The canvas coordinates at which the point is drawn.</li>
216<li>name: The name of the data series to which the point belongs</li>
217</ul>
5af2de24
DV
218</div>
219</body>
220</html>
221"""
222
a38e9336
DV
223# This page was super-helpful:
224# http://jsbeautifier.org/