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   <style type="text/css">
  63     p.option {
  64       padding-left: 25px;
  65       max-width: 800px;
  66     }
  67   </style>
  68 </head>
  69 <body>
  70 """
  71
  72 print 'Options categories:\n'
  73 print '<ul>\n'
  74 for label in sorted(labels):
  75   print '  <li><a href="#%s">%s</a>\n' % (label, label)
  76 print '</ul>\n\n'
  77
  78 def name(f):
  79   """Takes 'tests/demo.html' -> 'demo'"""
  80   return f.replace('tests/', '').replace('.html', '')
  81
  82 for label in sorted(labels):
  83   print '<a name="%s"><h2>%s</h2>\n' % (label, label)
  84
  85   for opt_name in sorted(docs.keys()):
  86     opt = docs[opt_name]
  87     if label not in opt['labels']: continue
  88     tests = opt['tests']
  89     if not tests:
  90       examples_html = '<font color=red>NONE</font>'
  91     else:
  92       examples_html = ' '.join(
  93         '<a href="%s">%s</a>' % (f, name(f)) for f in tests)
  94
  95     print """
  96   <p class='option'><b>%(name)s</b><br/>
  97   %(desc)s<br/>
  98   <i>Type: %(type)s<br/>
  99   Default: %(default)s</i><br/>
 100   Examples: %(examples_html)s<br/>
 101   <br/>
 102   """ % { 'name': opt_name,
 103           'type': opt['type'],
 104           'default': opt['default'],
 105           'desc': opt['description'],
 106           'examples_html': examples_html}
 107
 108
 109 # This page was super-helpful:
 110 # http://jsbeautifier.org/