More direct browser version verification test for filtering FF3.5.
[dygraphs.git] / generate-documentation.py
CommitLineData
0e37f8e5 1#!/usr/bin/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'] = []
33
88b1e052
DV
34# This is helpful for differentiating uses of options like 'width' and 'height'
35# from appearances of identically-named options in CSS.
0e37f8e5
DV
36def find_braces(txt):
37 """Really primitive method to find text inside of {..} braces.
38 Doesn't work if there's an unmatched brace in a string, e.g. '{'. """
39 out = ''
40 level = 0
41 for char in txt:
42 if char == '{':
43 level += 1
44 if level >= 1:
45 out += char
46 if char == '}':
47 level -= 1
48 return out
49
88b1e052
DV
50# Find text followed by a colon. These won't all be options, but those that
51# have the same name as a Dygraph option probably will be.
d1d19c3e
DV
52prop_re = re.compile(r'\b([a-zA-Z0-9]+) *:')
53tests = debug_tests or glob.glob('tests/*.html')
54for test_file in tests:
0e37f8e5 55 braced_html = find_braces(file(test_file).read())
d1d19c3e
DV
56 if debug_tests:
57 print braced_html
58
0e37f8e5
DV
59 ms = re.findall(prop_re, braced_html)
60 for opt in ms:
d1d19c3e 61 if debug_tests: print '\n'.join(ms)
0e37f8e5
DV
62 if opt in docs and test_file not in docs[opt]['tests']:
63 docs[opt]['tests'].append(test_file)
64
d1d19c3e
DV
65if debug_tests: sys.exit(0)
66
a38e9336
DV
67# Extract a labels list.
68labels = []
69for nu, opt in docs.iteritems():
70 for label in opt['labels']:
71 if label not in labels:
72 labels.append(label)
73
74print """
75<html>
76<head>
77 <title>Dygraphs Options Reference</title>
5af2de24 78 <link rel="stylesheet" href="style.css">
a38e9336
DV
79 <style type="text/css">
80 p.option {
81 padding-left: 25px;
5af2de24
DV
82 }
83 #nav {
84 position: fixed;
85 }
86 #content {
a38e9336
DV
87 max-width: 800px;
88 }
89 </style>
90</head>
91<body>
92"""
93
5af2de24
DV
94print """
95<div id=nav>
96<h2>Dygraphs</h2>
97<ul>
98 <li><a href="index.html">Home</a>
99 <li><a href="data.html">Data Formats</a></li>
100 <li><a href="annotations.html">Annotations</a></li>
101</ul>
102<h2>Options Reference</h2>
103<ul>
104 <li><a href="#usage">Usage</a>
105"""
a38e9336
DV
106for label in sorted(labels):
107 print ' <li><a href="#%s">%s</a>\n' % (label, label)
5af2de24 108print '</ul>\n</div>\n\n'
a38e9336 109
0e37f8e5 110def name(f):
88b1e052 111 """Takes 'tests/demo.html' -> 'demo'"""
0e37f8e5
DV
112 return f.replace('tests/', '').replace('.html', '')
113
5af2de24
DV
114print """
115<div id=content>
116<h2>Options Reference</h2>
117<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>
118
119<a name="usage"><h3>Usage</h3>
120<p>You specify options in the third parameter to the dygraphs constructor:
121<pre>g = new Dygraph(div,
122 data,
123 {
124 option1: value1,
125 option2: value2,
126 ...
127 });
128</pre>
129
130After you've created a Dygraph, you can change an option by calling the <code>updateOptions</code> method:
131<pre>g.updateOptions({
132 new_option1: value1,
133 new_option2: value2
134 });
135</pre>
136
137<p>And, without further ado, here's the complete list of options:</p>
138"""
a38e9336 139for label in sorted(labels):
5af2de24 140 print '<a name="%s"><h3>%s</h3>\n' % (label, label)
a38e9336
DV
141
142 for opt_name in sorted(docs.keys()):
143 opt = docs[opt_name]
144 if label not in opt['labels']: continue
145 tests = opt['tests']
146 if not tests:
147 examples_html = '<font color=red>NONE</font>'
148 else:
149 examples_html = ' '.join(
150 '<a href="%s">%s</a>' % (f, name(f)) for f in tests)
151
5af2de24
DV
152 if not opt['type']: opt['type'] = '(missing)'
153 if not opt['default']: opt['default'] = '(missing)'
154 if not opt['description']: opt['description'] = '(missing)'
155
a38e9336 156 print """
b5f3dd4e 157 <p class='option'><a name="%(name)s"/><b>%(name)s</b><br/>
a38e9336
DV
158 %(desc)s<br/>
159 <i>Type: %(type)s<br/>
160 Default: %(default)s</i><br/>
161 Examples: %(examples_html)s<br/>
162 <br/>
163 """ % { 'name': opt_name,
164 'type': opt['type'],
165 'default': opt['default'],
166 'desc': opt['description'],
167 'examples_html': examples_html}
0e37f8e5 168
0e37f8e5 169
5af2de24
DV
170print """
171</div>
172</body>
173</html>
174"""
175
a38e9336
DV
176# This page was super-helpful:
177# http://jsbeautifier.org/