generate-documentation.py

   1 #!/usr/bin/env python
   2
   3 # Generate docs/options.html
   4
   5 import json
   6 import glob
   7 import re
   8 import sys
   9
  10 # Set this to the path to a test file to get debug output for just that test
  11 # file. Can be helpful to figure out why a test is not being shown for a
  12 # particular option.
  13 debug_tests = []  # [ 'tests/zoom.html' ]
  14
  15 # Pull options reference JSON out of dygraph.js
  16 js = ''
  17 in_json = False
  18 for line in file('dygraph-options-reference.js'):
  19   if '<JSON>' in line:
  20     in_json = True
  21   elif '</JSON>' in line:
  22     in_json = False
  23   elif in_json:
  24     if line.endswith("\\\n"): # hacked in line continuation support with trailing \.
  25       line = line[:-2]
  26     js += line
  27
  28 # TODO(danvk): better errors here.
  29 assert js
  30 docs = json.loads(js)
  31
  32 # Go through the tests and find uses of each option.
  33 for opt in docs:
  34   docs[opt]['tests'] = []
  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 # Find text followed by a colon. These won't all be options, but those that
  53 # have the same name as a Dygraph option probably will be.
  54 prop_re = re.compile(r'\b([a-zA-Z0-9]+) *:')
  55 tests = debug_tests or glob.glob('tests/*.html')
  56 for test_file in tests:
  57   braced_html = find_braces(file(test_file).read())
  58   if debug_tests:
  59     print braced_html
  60
  61   ms = re.findall(prop_re, braced_html)
  62   for opt in ms:
  63     if debug_tests: print '\n'.join(ms)
  64     if opt in docs and test_file not in docs[opt]['tests']:
  65       docs[opt]['tests'].append(test_file)
  66
  67 if debug_tests: sys.exit(0)
  68
  69 # Extract a labels list.
  70 labels = []
  71 for nu, opt in docs.iteritems():
  72   for label in opt['labels']:
  73     if label not in labels:
  74       labels.append(label)
  75
  76 print """<!DOCTYPE HTML>
  77 <html>
  78 <head>
  79   <title>Dygraphs Options Reference</title>
  80   <link rel="stylesheet" href="style.css">
  81   <style type="text/css">
  82     p.option {
  83       padding-left: 25px;
  84     }
  85     div.parameters {
  86       padding-left: 15px;
  87     }
  88     #nav {
  89       position: fixed;
  90     }
  91     #content {
  92       max-width: 800px;
  93     }
  94   </style>
  95 </head>
  96 <body>
  97 """
  98
  99 print """
 100 <div id='nav'>
 101 <h2>Dygraphs</h2>
 102 <ul>
 103   <li><a href="index.html">Home</a>
 104   <li><a href="data.html">Data Formats</a></li>
 105   <li><a href="annotations.html">Annotations</a></li>
 106 </ul>
 107 <h2>Options Reference</h2>
 108 <ul>
 109   <li><a href="#usage">Usage</a>
 110 """
 111 for label in sorted(labels):
 112   print '  <li><a href="#%s">%s</a>\n' % (label, label)
 113 print '</ul>\n</div>\n\n'
 114
 115 def name(f):
 116   """Takes 'tests/demo.html' -> 'demo'"""
 117   return f.replace('tests/', '').replace('.html', '')
 118
 119 print """
 120 <div id='content'>
 121 <h2>Options Reference</h2>
 122 <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>
 123
 124 <a name="usage"></a><h3>Usage</h3>
 125 <p>You specify options in the third parameter to the dygraphs constructor:</p>
 126 <pre>g = new Dygraph(div,
 127                 data,
 128                 {
 129                   option1: value1,
 130                   option2: value2,
 131                   ...
 132                 });
 133 </pre>
 134
 135 <p>After you've created a Dygraph, you can change an option by calling the <code>updateOptions</code> method:</p>
 136 <pre>g.updateOptions({
 137                   new_option1: value1,
 138                   new_option2: value2
 139                 });
 140 </pre>
 141 <p>And, without further ado, here's the complete list of options:</p>
 142 """
 143 for label in sorted(labels):
 144   print '<a name="%s"><h3>%s</h3>\n' % (label, label)
 145
 146   for opt_name in sorted(docs.keys()):
 147     opt = docs[opt_name]
 148     if label not in opt['labels']: continue
 149     tests = opt['tests']
 150     if not tests:
 151       examples_html = '<font color=red>NONE</font>'
 152     else:
 153       examples_html = ' '.join(
 154         '<a href="%s">%s</a>' % (f, name(f)) for f in tests)
 155
 156     if 'parameters' in opt:
 157       parameters = opt['parameters']
 158       parameters_html = '\n'.join("<i>%s</i>: %s<br/>" % (p[0], p[1]) for p in parameters)
 159       parameters_html = "\n  <div class='parameters'>\n%s</div>" % (parameters_html);
 160     else:
 161       parameters_html = ''
 162
 163     if not opt['type']: opt['type'] = '(missing)'
 164     if not opt['default']: opt['default'] = '(missing)'
 165     if not opt['description']: opt['description'] = '(missing)'
 166
 167     print """
 168   <div class='option'><a name="%(name)s"></a><b>%(name)s</b><br/>
 169   %(desc)s<br/>
 170   <i>Type: %(type)s</i><br/>%(parameters)s
 171   <i>Default: %(default)s</i><br/>
 172   Examples: %(examples_html)s<br/>
 173   <br/></div>
 174   """ % { 'name': opt_name,
 175           'type': opt['type'],
 176           'parameters': parameters_html,
 177           'default': opt['default'],
 178           'desc': opt['description'],
 179           'examples_html': examples_html}
 180
 181
 182 print """
 183 <a name="point_properties"></a><h3>Point Properties</h3>
 184 Some callbacks take a point argument. Its properties are:<br/>
 185 <ul>
 186 <li>xval/yval: The data coordinates of the point (with dates/times as millis since epoch)</li>
 187 <li>canvasx/canvasy: The canvas coordinates at which the point is drawn.</li>
 188 <li>name: The name of the data series to which the point belongs</li>
 189 </ul>
 190 </div>
 191 </body>
 192 </html>
 193 """
 194
 195 # This page was super-helpful:
 196 # http://jsbeautifier.org/