Anatomy of a range selector
[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 _, opt in docs.iteritems():
84 for label in opt['labels']:
85 if label not in labels:
86 labels.append(label)
87
88 print """
89 <!--#include virtual="header.html" -->
90
91 <!--
92 DO NOT EDIT THIS FILE!
93
94 This file is generated by generate-documentation.py.
95 -->
96
97 <link rel=stylesheet href="options.css" />
98
99 """
100
101 print """
102 <div class="col-lg-3">
103 <div class="dygraphs-side-nav affix-top" data-spy="affix" data-offset-top="0">
104 <ul class='nav'>
105 <li><a href="#usage">Usage</a>
106 """
107 for label in sorted(labels):
108 print ' <li><a href="#%s">%s</a>\n' % (label, label)
109 print '</ul></div></div>\n\n'
110
111 print """
112 <div id='content' class='col-lg-9'>
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"></a><h3>Usage</h3>
117 <p>You specify options in the third parameter to the dygraphs constructor:</p>
118 <pre>g = new Dygraph(div,
119 data,
120 {
121 option1: value1,
122 option2: value2,
123 ...
124 });
125 </pre>
126
127 <p>After you've created a Dygraph, you can change an option by calling the <code>updateOptions</code> method:</p>
128 <pre>g.updateOptions({
129 new_option1: value1,
130 new_option2: value2
131 });
132 </pre>
133
134 <p>Some options can be set on a per-axis and per-series basis. See the docs on <a href="per-axis.html">per-axis and per-series options</a> to learn how to do this. The options which may be set in this way are marked as such on this page.</p>
135
136 <p>For options which are functions (e.g. callbacks and formatters), the value of <code>this</code> is set to the Dygraph object.</p>
137
138 <p>And, without further ado, here's the complete list of options:</p>
139 """
140
141 def test_name(f):
142 """Takes 'tests/demo.html' -> 'demo'"""
143 return f.replace('tests/', '').replace('.html', '')
144
145 def gallery_name(f):
146 """Takes 'gallery/demo.js' -> 'demo'"""
147 return f.replace('gallery/', '').replace('.js', '')
148
149 def urlify_gallery(f):
150 """Takes 'gallery/demo.js' -> 'demo'"""
151 return f.replace('gallery/', 'gallery/#g/').replace('.js', '')
152
153
154 for label in sorted(labels):
155 print '<a name="%s"></a><h3>%s</h3>\n' % (label, label)
156
157 for opt_name in sorted(docs.keys()):
158 opt = docs[opt_name]
159 if label not in opt['labels']: continue
160 tests = opt['tests']
161 if not tests:
162 examples_html = '<font color=red>NONE</font>'
163 else:
164 examples_html = ' '.join(
165 '<a href="%s">%s</a>' % (f, test_name(f)) for f in tests)
166
167 gallery = opt['gallery']
168 if not gallery:
169 gallery_html = '<font color=red>NONE</font>'
170 else:
171 gallery_html = ' '.join(
172 '<a href="%s">%s</a>' % (urlify_gallery(f), gallery_name(f)) for f in gallery)
173
174 if 'parameters' in opt:
175 parameters = opt['parameters']
176 parameters_html = '\n'.join("<i>%s</i>: %s<br/>" % (p[0], p[1]) for p in parameters)
177 parameters_html = "\n <div class='parameters'>\n%s</div>" % (parameters_html);
178 else:
179 parameters_html = ''
180
181 if not opt['type']: opt['type'] = '(missing)'
182 if not opt['default']: opt['default'] = '(missing)'
183 if not opt['description']: opt['description'] = '(missing)'
184
185 print """
186 <div class='option'><a name="%(name)s"></a><b>%(name)s</b>
187 <a class="link" href="#%(name)s">#</a>
188 <br/>
189 <p>%(desc)s</p>
190 <i>Type: %(type)s</i><br/>%(parameters)s
191 <i>Default: %(default)s</i></p>
192 Gallery Samples: %(gallery_html)s<br/>
193 Other Examples: %(examples_html)s<br/>
194 <br/></div>
195 """ % { 'name': opt_name,
196 'type': opt['type'],
197 'parameters': parameters_html,
198 'default': opt['default'],
199 'desc': opt['description'],
200 'examples_html': examples_html,
201 'gallery_html': gallery_html}
202
203
204 print """
205 <a name="point_properties"></a><h3>Point Properties</h3>
206 Some callbacks take a point argument. Its properties are:<br/>
207 <ul>
208 <li>xval/yval: The data coordinates of the point (with dates/times as millis since epoch)</li>
209 <li>canvasx/canvasy: The canvas coordinates at which the point is drawn.</li>
210 <li>name: The name of the data series to which the point belongs</li>
211 <li>idx: The row number of the point in the data set</li>
212 </ul>
213 </div> <!-- #content -->
214
215 <!--#include virtual="footer.html" -->
216 """
217
218 # This page was super-helpful:
219 # http://jsbeautifier.org/