[dygraphs.git] / generate-documentation.py

#!/usr/bin/python
import json
import glob
import re

# Pull options reference JSON out of dygraph.js
js = ''
in_json = False
for line in file('dygraph.js'):
  if '<JSON>' in line:
    in_json = True
  elif '</JSON>' in line:
    in_json = False
  elif in_json:
    js += line

# TODO(danvk): better errors here.
assert js
docs = json.loads(js)

# Go through the tests and find uses of each option.
for opt in docs:
  docs[opt]['tests'] = []

# This is helpful for differentiating uses of options like 'width' and 'height'
# from appearances of identically-named options in CSS.
def find_braces(txt):
  """Really primitive method to find text inside of {..} braces.
  Doesn't work if there's an unmatched brace in a string, e.g. '{'. """
  out = ''
  level = 0
  for char in txt:
    if char == '{':
      level += 1
    if level >= 1:
      out += char
    if char == '}':
      level -= 1
  return out

# Find text followed by a colon. These won't all be options, but those that
# have the same name as a Dygraph option probably will be.
prop_re = re.compile(r'\b([a-zA-Z0-9]+):')
for test_file in glob.glob('tests/*.html'):
  braced_html = find_braces(file(test_file).read())
  ms = re.findall(prop_re, braced_html)
  for opt in ms:
    if opt in docs and test_file not in docs[opt]['tests']:
      docs[opt]['tests'].append(test_file)

# Extract a labels list.
labels = []
for nu, opt in docs.iteritems():
  for label in opt['labels']:
    if label not in labels:
      labels.append(label)

print """
<html>
<head>
  <title>Dygraphs Options Reference</title>
  <link rel="stylesheet" href="style.css">
  <style type="text/css">
    p.option {
      padding-left: 25px;
    }
    #nav {
      position: fixed;
    }
    #content {
      max-width: 800px;
    }
  </style>
</head>
<body>
"""

print """
<div id=nav>
<h2>Dygraphs</h2>
<ul>
  <li><a href="index.html">Home</a>
  <li><a href="data.html">Data Formats</a></li>
  <li><a href="annotations.html">Annotations</a></li>
</ul>
<h2>Options Reference</h2>
<ul>
  <li><a href="#usage">Usage</a>
"""
for label in sorted(labels):
  print '  <li><a href="#%s">%s</a>\n' % (label, label)
print '</ul>\n</div>\n\n'

def name(f):
  """Takes 'tests/demo.html' -> 'demo'"""
  return f.replace('tests/', '').replace('.html', '')

print """
<div id=content>
<h2>Options Reference</h2>
<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>

<a name="usage"><h3>Usage</h3>
<p>You specify options in the third parameter to the dygraphs constructor:
<pre>g = new Dygraph(div,
                data,
                {
                  option1: value1,
                  option2: value2,
                  ...
                });
</pre>

After you've created a Dygraph, you can change an option by calling the <code>updateOptions</code> method:
<pre>g.updateOptions({
                  new_option1: value1,
                  new_option2: value2
                });
</pre>

<p>And, without further ado, here's the complete list of options:</p>
"""
for label in sorted(labels):
  print '<a name="%s"><h3>%s</h3>\n' % (label, label)

  for opt_name in sorted(docs.keys()):
    opt = docs[opt_name]
    if label not in opt['labels']: continue
    tests = opt['tests']
    if not tests:
      examples_html = '<font color=red>NONE</font>'
    else:
      examples_html = ' '.join(
        '<a href="%s">%s</a>' % (f, name(f)) for f in tests)

    if not opt['type']: opt['type'] = '(missing)'
    if not opt['default']: opt['default'] = '(missing)'
    if not opt['description']: opt['description'] = '(missing)'

    print """
  <p class='option'><a name="%(name)s"/><b>%(name)s</b><br/>
  %(desc)s<br/>
  <i>Type: %(type)s<br/>
  Default: %(default)s</i><br/>
  Examples: %(examples_html)s<br/>
  <br/>
  """ % { 'name': opt_name,
          'type': opt['type'],
          'default': opt['default'],
          'desc': opt['description'],
          'examples_html': examples_html}


print """
</div>
</body>
</html>
"""

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