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 def name(f):
  52   """Takes 'tests/demo.html' -> 'demo'"""
  53   return f.replace('tests/', '').replace('.html', '')
  54
  55 for opt_name in sorted(docs.keys()):
  56   opt = docs[opt_name]
  57   tests = opt['tests']
  58   if not tests:
  59     examples_html = '<font color=red>NONE</font>'
  60   else:
  61     examples_html = ' '.join(
  62       '<a href="%s">%s</a>' % (f, name(f)) for f in tests)
  63
  64   print """
  65 <p><b>%(name)s</b><br/>
  66 %(desc)s<br/>
  67 <i>Type: %(type)s<br/>
  68 Default: %(default)s</i><br/>
  69 Examples: %(examples_html)s<br/>
  70 <br/>
  71 """ % { 'name': opt_name,
  72         'type': opt['type'],
  73         'default': opt['default'],
  74         'desc': opt['description'],
  75         'examples_html': examples_html}
  76