Commit | Line | Data |
---|---|---|
db071c3e | 1 | #!/usr/bin/env python |
ea910bfa RK |
2 | |
3 | # Generate docs/options.html | |
4 | ||
0e37f8e5 DV |
5 | import json |
6 | import glob | |
7 | import re | |
d1d19c3e DV |
8 | import 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. | |
13 | debug_tests = [] # [ 'tests/zoom.html' ] | |
0e37f8e5 | 14 | |
88b1e052 | 15 | # Pull options reference JSON out of dygraph.js |
0e37f8e5 DV |
16 | js = '' |
17 | in_json = False | |
730852d8 | 18 | for 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. | |
27 | assert js | |
28 | docs = json.loads(js) | |
29 | ||
30 | # Go through the tests and find uses of each option. | |
31 | for 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 |
37 | def 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 |
51 | def 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: | |
56 | braced_html = find_braces(file(test_file).read()) | |
57 | if debug_tests: | |
58 | print braced_html | |
59 | ||
60 | ms = re.findall(prop_re, braced_html) | |
61 | for opt in ms: | |
62 | if debug_tests: print '\n'.join(ms) | |
63 | if opt in docs and test_file not in docs[opt][type]: | |
64 | docs[opt][type].append(test_file) | |
65 | ||
66 | search_files("tests", glob.glob("tests/*.html")) | |
67 | search_files("gallery", glob.glob("gallery/*.js")) #TODO add grep "Gallery.register\(" | |
0e37f8e5 | 68 | |
d1d19c3e DV |
69 | if debug_tests: sys.exit(0) |
70 | ||
a38e9336 DV |
71 | # Extract a labels list. |
72 | labels = [] | |
73 | for nu, opt in docs.iteritems(): | |
74 | for label in opt['labels']: | |
75 | if label not in labels: | |
76 | labels.append(label) | |
77 | ||
b5bdd85b | 78 | print """<!DOCTYPE HTML> |
a38e9336 DV |
79 | <html> |
80 | <head> | |
81 | <title>Dygraphs Options Reference</title> | |
5af2de24 | 82 | <link rel="stylesheet" href="style.css"> |
a38e9336 DV |
83 | <style type="text/css"> |
84 | p.option { | |
85 | padding-left: 25px; | |
5af2de24 | 86 | } |
b5bdd85b RK |
87 | div.parameters { |
88 | padding-left: 15px; | |
89 | } | |
5af2de24 DV |
90 | #nav { |
91 | position: fixed; | |
92 | } | |
93 | #content { | |
a38e9336 DV |
94 | max-width: 800px; |
95 | } | |
96 | </style> | |
97 | </head> | |
98 | <body> | |
99 | """ | |
100 | ||
5af2de24 | 101 | print """ |
b5bdd85b | 102 | <div id='nav'> |
5af2de24 DV |
103 | <h2>Dygraphs</h2> |
104 | <ul> | |
105 | <li><a href="index.html">Home</a> | |
106 | <li><a href="data.html">Data Formats</a></li> | |
107 | <li><a href="annotations.html">Annotations</a></li> | |
108 | </ul> | |
109 | <h2>Options Reference</h2> | |
110 | <ul> | |
111 | <li><a href="#usage">Usage</a> | |
112 | """ | |
a38e9336 DV |
113 | for label in sorted(labels): |
114 | print ' <li><a href="#%s">%s</a>\n' % (label, label) | |
5af2de24 | 115 | print '</ul>\n</div>\n\n' |
a38e9336 | 116 | |
5af2de24 | 117 | print """ |
b5bdd85b | 118 | <div id='content'> |
5af2de24 DV |
119 | <h2>Options Reference</h2> |
120 | <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> | |
121 | ||
b5bdd85b RK |
122 | <a name="usage"></a><h3>Usage</h3> |
123 | <p>You specify options in the third parameter to the dygraphs constructor:</p> | |
5af2de24 DV |
124 | <pre>g = new Dygraph(div, |
125 | data, | |
126 | { | |
127 | option1: value1, | |
128 | option2: value2, | |
129 | ... | |
130 | }); | |
131 | </pre> | |
132 | ||
b5bdd85b | 133 | <p>After you've created a Dygraph, you can change an option by calling the <code>updateOptions</code> method:</p> |
5af2de24 DV |
134 | <pre>g.updateOptions({ |
135 | new_option1: value1, | |
136 | new_option2: value2 | |
137 | }); | |
138 | </pre> | |
5af2de24 DV |
139 | <p>And, without further ado, here's the complete list of options:</p> |
140 | """ | |
473278ec RK |
141 | |
142 | def de_tests(f): | |
143 | """Takes 'tests/demo.html' -> 'demo'""" | |
144 | return f.replace('tests/', '').replace('.html', '') | |
145 | ||
146 | def de_gallery(f): | |
147 | """Takes 'gallery/demo.js' -> 'demo'""" | |
148 | return f.replace('gallery/', '').replace('.js', '') | |
149 | ||
150 | def urlify_gallery(f): | |
151 | """Takes 'gallery/demo.js' -> 'demo'""" | |
152 | return f.replace('gallery/', 'gallery/#g/').replace('.js', '') | |
153 | ||
154 | ||
a38e9336 | 155 | for label in sorted(labels): |
5af2de24 | 156 | print '<a name="%s"><h3>%s</h3>\n' % (label, label) |
a38e9336 DV |
157 | |
158 | for opt_name in sorted(docs.keys()): | |
159 | opt = docs[opt_name] | |
160 | if label not in opt['labels']: continue | |
161 | tests = opt['tests'] | |
162 | if not tests: | |
163 | examples_html = '<font color=red>NONE</font>' | |
164 | else: | |
165 | examples_html = ' '.join( | |
473278ec RK |
166 | '<a href="%s">%s</a>' % (f, de_tests(f)) for f in tests) |
167 | ||
168 | gallery = opt['gallery'] | |
169 | if not gallery: | |
170 | gallery_html = '<font color=red>NONE</font>' | |
171 | else: | |
172 | gallery_html = ' '.join( | |
173 | '<a href="%s">%s</a>' % (urlify_gallery(f), de_gallery(f)) for f in gallery) | |
a38e9336 | 174 | |
b5bdd85b RK |
175 | if 'parameters' in opt: |
176 | parameters = opt['parameters'] | |
177 | parameters_html = '\n'.join("<i>%s</i>: %s<br/>" % (p[0], p[1]) for p in parameters) | |
178 | parameters_html = "\n <div class='parameters'>\n%s</div>" % (parameters_html); | |
179 | else: | |
180 | parameters_html = '' | |
181 | ||
5af2de24 DV |
182 | if not opt['type']: opt['type'] = '(missing)' |
183 | if not opt['default']: opt['default'] = '(missing)' | |
184 | if not opt['description']: opt['description'] = '(missing)' | |
185 | ||
a38e9336 | 186 | print """ |
b5bdd85b | 187 | <div class='option'><a name="%(name)s"></a><b>%(name)s</b><br/> |
a38e9336 | 188 | %(desc)s<br/> |
b5bdd85b RK |
189 | <i>Type: %(type)s</i><br/>%(parameters)s |
190 | <i>Default: %(default)s</i><br/> | |
2941da80 RK |
191 | Gallery Samples: %(gallery_html)s<br/> |
192 | Other Examples: %(examples_html)s<br/> | |
b5bdd85b | 193 | <br/></div> |
a38e9336 DV |
194 | """ % { 'name': opt_name, |
195 | 'type': opt['type'], | |
b5bdd85b | 196 | 'parameters': parameters_html, |
a38e9336 DV |
197 | 'default': opt['default'], |
198 | 'desc': opt['description'], | |
473278ec RK |
199 | 'examples_html': examples_html, |
200 | 'gallery_html': gallery_html} | |
0e37f8e5 | 201 | |
0e37f8e5 | 202 | |
5af2de24 | 203 | print """ |
b5bdd85b RK |
204 | <a name="point_properties"></a><h3>Point Properties</h3> |
205 | Some callbacks take a point argument. Its properties are:<br/> | |
206 | <ul> | |
207 | <li>xval/yval: The data coordinates of the point (with dates/times as millis since epoch)</li> | |
208 | <li>canvasx/canvasy: The canvas coordinates at which the point is drawn.</li> | |
209 | <li>name: The name of the data series to which the point belongs</li> | |
210 | </ul> | |
5af2de24 DV |
211 | </div> |
212 | </body> | |
213 | </html> | |
214 | """ | |
215 | ||
a38e9336 DV |
216 | # This page was super-helpful: |
217 | # http://jsbeautifier.org/ |