[dygraphs.git] / generate-documentation.py

#!/usr/bin/env python

# Generate docs/options.html

import glob
import json
import os
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'] = []
  docs[opt]['gallery'] = []

# 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

def search_files(type, files):
  # 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 files:
    if os.path.isfile(test_file): # Basically skips directories
      text = file(test_file).read()

      # Hack for slipping past gallery demos that have title in their attributes
      # so they don't appear as reasons for the demo to have 'title' options.
      if type == "gallery":
        idx = text.find("function(")
        if idx >= 0:
          text = text[idx:]
      braced_html = find_braces(text)
      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][type]:
          docs[opt][type].append(test_file)

search_files("tests", glob.glob("tests/*.html"))
search_files("gallery", glob.glob("gallery/*.js")) #TODO add grep "Gallery.register\("

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 """<!DOCTYPE HTML>
<html>
<head>
  <title>Dygraphs Options Reference</title>
  <link rel="stylesheet" href="style.css">
  <style type="text/css">
    p.option {
      padding-left: 25px;
    }
    div.parameters {
      padding-left: 15px;
    }
    #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'

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

<p>After you've created a Dygraph, you can change an option by calling the <code>updateOptions</code> method:</p>
<pre>g.updateOptions({
                  new_option1: value1,
                  new_option2: value2
                });
</pre>
<p>And, without further ado, here's the complete list of options:</p>
"""

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

def gallery_name(f):
  """Takes 'gallery/demo.js' -> 'demo'"""
  return f.replace('gallery/', '').replace('.js', '')

def urlify_gallery(f):
  """Takes 'gallery/demo.js' -> 'demo'"""
  return f.replace('gallery/', 'gallery/#g/').replace('.js', '')


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, test_name(f)) for f in tests)

    gallery = opt['gallery']
    if not gallery:
      gallery_html = '<font color=red>NONE</font>'
    else:
      gallery_html = ' '.join(
        '<a href="%s">%s</a>' % (urlify_gallery(f), gallery_name(f)) for f in gallery)

    if 'parameters' in opt:
      parameters = opt['parameters']
      parameters_html = '\n'.join("<i>%s</i>: %s<br/>" % (p[0], p[1]) for p in parameters)
      parameters_html = "\n  <div class='parameters'>\n%s</div>" % (parameters_html);
    else:
      parameters_html = ''

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

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


print """
<a name="point_properties"></a><h3>Point Properties</h3>
Some callbacks take a point argument. Its properties are:<br/>
<ul>
<li>xval/yval: The data coordinates of the point (with dates/times as millis since epoch)</li>
<li>canvasx/canvasy: The canvas coordinates at which the point is drawn.</li>
<li>name: The name of the data series to which the point belongs</li>
</ul>
</div>
</body>
</html>
"""

# This page was super-helpful:
# http://jsbeautifier.org/
Commit	Line	Data
db071c3e	1	#!/usr/bin/env python
ea910bfa RK	2
	3	# Generate docs/options.html
	4
0e37f8e5	5	import glob
b8ef8716 RK	6	import json
b8ef8716 RK	7	import os
0e37f8e5	8	import re
d1d19c3e DV	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' ]
0e37f8e5	15
88b1e052	16	# Pull options reference JSON out of dygraph.js
0e37f8e5 DV	17	js = ''
0e37f8e5 DV	18	in_json = False
730852d8	19	for 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.
	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'] = []
473278ec	34	docs[opt]['gallery'] = []
0e37f8e5	35
88b1e052 DV	36	# This is helpful for differentiating uses of options like 'width' and 'height'
88b1e052 DV	37	# from appearances of identically-named options in CSS.
0e37f8e5 DV	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
473278ec RK	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:
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
	76	search_files("tests", glob.glob("tests/*.html"))
	77	search_files("gallery", glob.glob("gallery/*.js")) #TODO add grep "Gallery.register\("
0e37f8e5	78
d1d19c3e DV	79	if debug_tests: sys.exit(0)
d1d19c3e DV	80
a38e9336 DV	81	# Extract a labels list.
	82	labels = []
	83	for nu, opt in docs.iteritems():
	84	for label in opt['labels']:
	85	if label not in labels:
	86	labels.append(label)
	87
b5bdd85b	88	print """<!DOCTYPE HTML>
a38e9336 DV	89	<html>
	90	<head>
	91	<title>Dygraphs Options Reference</title>
5af2de24	92	<link rel="stylesheet" href="style.css">
a38e9336 DV	93	<style type="text/css">
	94	p.option {
	95	padding-left: 25px;
5af2de24	96	}
b5bdd85b RK	97	div.parameters {
	98	padding-left: 15px;
	99	}
5af2de24 DV	100	#nav {
	101	position: fixed;
	102	}
	103	#content {
a38e9336 DV	104	max-width: 800px;
	105	}
	106	</style>
	107	</head>
	108	<body>
	109	"""
	110
5af2de24	111	print """
b5bdd85b	112	<div id='nav'>
5af2de24 DV	113	<h2>Dygraphs</h2>
	114	<ul>
	115	<li><a href="index.html">Home</a>
	116	<li><a href="data.html">Data Formats</a></li>
	117	<li><a href="annotations.html">Annotations</a></li>
	118	</ul>
	119	<h2>Options Reference</h2>
	120	<ul>
	121	<li><a href="#usage">Usage</a>
	122	"""
a38e9336 DV	123	for label in sorted(labels):
a38e9336 DV	124	print ' <li><a href="#%s">%s</a>\n' % (label, label)
5af2de24	125	print '</ul>\n</div>\n\n'
a38e9336	126
5af2de24	127	print """
b5bdd85b	128	<div id='content'>
5af2de24 DV	129	<h2>Options Reference</h2>
	130	<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>
	131
b5bdd85b RK	132	<a name="usage"></a><h3>Usage</h3>
b5bdd85b RK	133	<p>You specify options in the third parameter to the dygraphs constructor:</p>
5af2de24 DV	134	<pre>g = new Dygraph(div,
	135	data,
	136	{
	137	option1: value1,
	138	option2: value2,
	139	...
	140	});
	141	</pre>
	142
b5bdd85b	143	<p>After you've created a Dygraph, you can change an option by calling the <code>updateOptions</code> method:</p>
5af2de24 DV	144	<pre>g.updateOptions({
	145	new_option1: value1,
	146	new_option2: value2
	147	});
	148	</pre>
5af2de24 DV	149	<p>And, without further ado, here's the complete list of options:</p>
5af2de24 DV	150	"""
473278ec	151
0295cce3	152	def test_name(f):
473278ec RK	153	"""Takes 'tests/demo.html' -> 'demo'"""
	154	return f.replace('tests/', '').replace('.html', '')
	155
0295cce3	156	def gallery_name(f):
473278ec RK	157	"""Takes 'gallery/demo.js' -> 'demo'"""
	158	return f.replace('gallery/', '').replace('.js', '')
	159
	160	def urlify_gallery(f):
	161	"""Takes 'gallery/demo.js' -> 'demo'"""
	162	return f.replace('gallery/', 'gallery/#g/').replace('.js', '')
	163
	164
a38e9336	165	for label in sorted(labels):
5af2de24	166	print '<a name="%s"><h3>%s</h3>\n' % (label, label)
a38e9336 DV	167
	168	for opt_name in sorted(docs.keys()):
	169	opt = docs[opt_name]
	170	if label not in opt['labels']: continue
	171	tests = opt['tests']
	172	if not tests:
	173	examples_html = '<font color=red>NONE</font>'
	174	else:
	175	examples_html = ' '.join(
0295cce3	176	'<a href="%s">%s</a>' % (f, test_name(f)) for f in tests)
473278ec RK	177
	178	gallery = opt['gallery']
	179	if not gallery:
	180	gallery_html = '<font color=red>NONE</font>'
	181	else:
	182	gallery_html = ' '.join(
0295cce3	183	'<a href="%s">%s</a>' % (urlify_gallery(f), gallery_name(f)) for f in gallery)
a38e9336	184
b5bdd85b RK	185	if 'parameters' in opt:
	186	parameters = opt['parameters']
	187	parameters_html = '\n'.join("<i>%s</i>: %s<br/>" % (p[0], p[1]) for p in parameters)
	188	parameters_html = "\n <div class='parameters'>\n%s</div>" % (parameters_html);
	189	else:
	190	parameters_html = ''
	191
5af2de24 DV	192	if not opt['type']: opt['type'] = '(missing)'
	193	if not opt['default']: opt['default'] = '(missing)'
	194	if not opt['description']: opt['description'] = '(missing)'
	195
a38e9336	196	print """
b5bdd85b	197	<div class='option'><a name="%(name)s"></a><b>%(name)s</b><br/>
11c49f0e	198	<p>%(desc)s</p>
b5bdd85b	199	<i>Type: %(type)s</i><br/>%(parameters)s
11c49f0e	200	<i>Default: %(default)s</i></p>
2941da80 RK	201	Gallery Samples: %(gallery_html)s<br/>
2941da80 RK	202	Other Examples: %(examples_html)s<br/>
b5bdd85b	203	<br/></div>
a38e9336 DV	204	""" % { 'name': opt_name,
a38e9336 DV	205	'type': opt['type'],
b5bdd85b	206	'parameters': parameters_html,
a38e9336 DV	207	'default': opt['default'],
a38e9336 DV	208	'desc': opt['description'],
473278ec RK	209	'examples_html': examples_html,
473278ec RK	210	'gallery_html': gallery_html}
0e37f8e5	211
0e37f8e5	212
5af2de24	213	print """
b5bdd85b RK	214	<a name="point_properties"></a><h3>Point Properties</h3>
	215	Some callbacks take a point argument. Its properties are:<br/>
	216	<ul>
	217	<li>xval/yval: The data coordinates of the point (with dates/times as millis since epoch)</li>
	218	<li>canvasx/canvasy: The canvas coordinates at which the point is drawn.</li>
	219	<li>name: The name of the data series to which the point belongs</li>
	220	</ul>
5af2de24 DV	221	</div>
	222	</body>
	223	</html>
	224	"""
	225
a38e9336 DV	226	# This page was super-helpful:
a38e9336 DV	227	# http://jsbeautifier.org/