generate-documentation.py

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