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