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