generate-documentation.py

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