generate-documentation.py

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