tweak link
[dygraphs.git] / generate-documentation.py
CommitLineData
db071c3e 1#!/usr/bin/env python
ea910bfa
RK
2
3# Generate docs/options.html
4
0e37f8e5 5import glob
b8ef8716
RK
6import json
7import os
0e37f8e5 8import re
d1d19c3e
DV
9import 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.
14debug_tests = [] # [ 'tests/zoom.html' ]
0e37f8e5 15
88b1e052 16# Pull options reference JSON out of dygraph.js
0e37f8e5
DV
17js = ''
18in_json = False
730852d8 19for line in file('dygraph-options-reference.js'):
0e37f8e5
DV
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.
28assert js
29docs = json.loads(js)
30
31# Go through the tests and find uses of each option.
32for opt in docs:
33 docs[opt]['tests'] = []
473278ec 34 docs[opt]['gallery'] = []
0e37f8e5 35
88b1e052
DV
36# This is helpful for differentiating uses of options like 'width' and 'height'
37# from appearances of identically-named options in CSS.
0e37f8e5
DV
38def 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
473278ec
RK
52def 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:
b8ef8716
RK
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
473278ec 69
b8ef8716
RK
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)
473278ec
RK
75
76search_files("tests", glob.glob("tests/*.html"))
77search_files("gallery", glob.glob("gallery/*.js")) #TODO add grep "Gallery.register\("
0e37f8e5 78
d1d19c3e
DV
79if debug_tests: sys.exit(0)
80
a38e9336
DV
81# Extract a labels list.
82labels = []
14403441 83for _, opt in docs.iteritems():
a38e9336
DV
84 for label in opt['labels']:
85 if label not in labels:
86 labels.append(label)
87
14403441
DV
88print """
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
a38e9336
DV
99"""
100
5af2de24 101print """
14403441
DV
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'>
5af2de24
DV
105 <li><a href="#usage">Usage</a>
106"""
a38e9336
DV
107for label in sorted(labels):
108 print ' <li><a href="#%s">%s</a>\n' % (label, label)
14403441 109print '</ul></div></div>\n\n'
a38e9336 110
5af2de24 111print """
14403441 112<div id='content' class='col-lg-9'>
5af2de24
DV
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
b5bdd85b
RK
116<a name="usage"></a><h3>Usage</h3>
117<p>You specify options in the third parameter to the dygraphs constructor:</p>
5af2de24
DV
118<pre>g = new Dygraph(div,
119 data,
120 {
121 option1: value1,
122 option2: value2,
123 ...
124 });
125</pre>
126
b5bdd85b 127<p>After you've created a Dygraph, you can change an option by calling the <code>updateOptions</code> method:</p>
5af2de24
DV
128<pre>g.updateOptions({
129 new_option1: value1,
130 new_option2: value2
131 });
132</pre>
14403441
DV
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
5af2de24
DV
136<p>And, without further ado, here's the complete list of options:</p>
137"""
473278ec 138
0295cce3 139def test_name(f):
473278ec
RK
140 """Takes 'tests/demo.html' -> 'demo'"""
141 return f.replace('tests/', '').replace('.html', '')
142
0295cce3 143def gallery_name(f):
473278ec
RK
144 """Takes 'gallery/demo.js' -> 'demo'"""
145 return f.replace('gallery/', '').replace('.js', '')
146
147def urlify_gallery(f):
148 """Takes 'gallery/demo.js' -> 'demo'"""
149 return f.replace('gallery/', 'gallery/#g/').replace('.js', '')
150
151
a38e9336 152for label in sorted(labels):
fd81b1d8 153 print '<a name="%s"></a><h3>%s</h3>\n' % (label, label)
a38e9336
DV
154
155 for opt_name in sorted(docs.keys()):
156 opt = docs[opt_name]
157 if label not in opt['labels']: continue
158 tests = opt['tests']
159 if not tests:
160 examples_html = '<font color=red>NONE</font>'
161 else:
162 examples_html = ' '.join(
0295cce3 163 '<a href="%s">%s</a>' % (f, test_name(f)) for f in tests)
473278ec
RK
164
165 gallery = opt['gallery']
166 if not gallery:
167 gallery_html = '<font color=red>NONE</font>'
168 else:
169 gallery_html = ' '.join(
0295cce3 170 '<a href="%s">%s</a>' % (urlify_gallery(f), gallery_name(f)) for f in gallery)
a38e9336 171
b5bdd85b
RK
172 if 'parameters' in opt:
173 parameters = opt['parameters']
174 parameters_html = '\n'.join("<i>%s</i>: %s<br/>" % (p[0], p[1]) for p in parameters)
175 parameters_html = "\n <div class='parameters'>\n%s</div>" % (parameters_html);
176 else:
177 parameters_html = ''
178
5af2de24
DV
179 if not opt['type']: opt['type'] = '(missing)'
180 if not opt['default']: opt['default'] = '(missing)'
181 if not opt['description']: opt['description'] = '(missing)'
182
a38e9336 183 print """
fd81b1d8
DV
184 <div class='option'><a name="%(name)s"></a><b>%(name)s</b>
185 <a class="link" href="#%(name)s">#</a>
186 <br/>
11c49f0e 187 <p>%(desc)s</p>
b5bdd85b 188 <i>Type: %(type)s</i><br/>%(parameters)s
11c49f0e 189 <i>Default: %(default)s</i></p>
2941da80
RK
190 Gallery Samples: %(gallery_html)s<br/>
191 Other Examples: %(examples_html)s<br/>
b5bdd85b 192 <br/></div>
a38e9336
DV
193 """ % { 'name': opt_name,
194 'type': opt['type'],
b5bdd85b 195 'parameters': parameters_html,
a38e9336
DV
196 'default': opt['default'],
197 'desc': opt['description'],
473278ec
RK
198 'examples_html': examples_html,
199 'gallery_html': gallery_html}
0e37f8e5 200
0e37f8e5 201
5af2de24 202print """
b5bdd85b
RK
203<a name="point_properties"></a><h3>Point Properties</h3>
204Some callbacks take a point argument. Its properties are:<br/>
205<ul>
206<li>xval/yval: The data coordinates of the point (with dates/times as millis since epoch)</li>
207<li>canvasx/canvasy: The canvas coordinates at which the point is drawn.</li>
208<li>name: The name of the data series to which the point belongs</li>
867786ec 209<li>idx: The row number of the point in the data set</li>
b5bdd85b 210</ul>
14403441
DV
211</div> <!-- #content -->
212
213<!--#include virtual="footer.html" -->
5af2de24
DV
214"""
215
a38e9336
DV
216# This page was super-helpful:
217# http://jsbeautifier.org/