[dygraphs.git] / generate-documentation.py

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

# Set this to the path to a test file to get debug output for just that test
# file. Can be helpful to figure out why a test is not being shown for a
# particular option.
debug_tests = []  # [ 'tests/zoom.html' ]

# Pull options reference JSON out of dygraph.js
js = ''
in_json = False
for line in file('dygraph-options-reference.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]+) *:')
tests = debug_tests or glob.glob('tests/*.html')
for test_file in tests:
  braced_html = find_braces(file(test_file).read())
  if debug_tests:
    print braced_html

  ms = re.findall(prop_re, braced_html)
  for opt in ms:
    if debug_tests: print '\n'.join(ms)
    if opt in docs and test_file not in docs[opt]['tests']:
      docs[opt]['tests'].append(test_file)

if debug_tests: sys.exit(0)

# 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
d1d19c3e DV	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' ]
0e37f8e5	11
88b1e052	12	# Pull options reference JSON out of dygraph.js
0e37f8e5 DV	13	js = ''
0e37f8e5 DV	14	in_json = False
730852d8	15	for line in file('dygraph-options-reference.js'):
0e37f8e5 DV	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
88b1e052 DV	31	# This is helpful for differentiating uses of options like 'width' and 'height'
88b1e052 DV	32	# from appearances of identically-named options in CSS.
0e37f8e5 DV	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
88b1e052 DV	47	# Find text followed by a colon. These won't all be options, but those that
88b1e052 DV	48	# have the same name as a Dygraph option probably will be.
d1d19c3e DV	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:
0e37f8e5	52	braced_html = find_braces(file(test_file).read())
d1d19c3e DV	53	if debug_tests:
	54	print braced_html
	55
0e37f8e5 DV	56	ms = re.findall(prop_re, braced_html)
0e37f8e5 DV	57	for opt in ms:
d1d19c3e	58	if debug_tests: print '\n'.join(ms)
0e37f8e5 DV	59	if opt in docs and test_file not in docs[opt]['tests']:
	60	docs[opt]['tests'].append(test_file)
	61
d1d19c3e DV	62	if debug_tests: sys.exit(0)
d1d19c3e DV	63
a38e9336 DV	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>
5af2de24	75	<link rel="stylesheet" href="style.css">
a38e9336 DV	76	<style type="text/css">
	77	p.option {
	78	padding-left: 25px;
5af2de24 DV	79	}
	80	#nav {
	81	position: fixed;
	82	}
	83	#content {
a38e9336 DV	84	max-width: 800px;
	85	}
	86	</style>
	87	</head>
	88	<body>
	89	"""
	90
5af2de24 DV	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	"""
a38e9336 DV	103	for label in sorted(labels):
a38e9336 DV	104	print ' <li><a href="#%s">%s</a>\n' % (label, label)
5af2de24	105	print '</ul>\n</div>\n\n'
a38e9336	106
0e37f8e5	107	def name(f):
88b1e052	108	"""Takes 'tests/demo.html' -> 'demo'"""
0e37f8e5 DV	109	return f.replace('tests/', '').replace('.html', '')
0e37f8e5 DV	110
5af2de24 DV	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	"""
a38e9336	136	for label in sorted(labels):
5af2de24	137	print '<a name="%s"><h3>%s</h3>\n' % (label, label)
a38e9336 DV	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
5af2de24 DV	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
a38e9336	153	print """
b5f3dd4e	154	<p class='option'><a name="%(name)s"/><b>%(name)s</b><br/>
a38e9336 DV	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}
0e37f8e5	165
0e37f8e5	166
5af2de24 DV	167	print """
	168	</div>
	169	</body>
	170	</html>
	171	"""
	172
a38e9336 DV	173	# This page was super-helpful:
a38e9336 DV	174	# http://jsbeautifier.org/