generate-documentation.py

   1 #!/usr/bin/env 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   docs[opt]['gallery'] = []
  34
  35 # This is helpful for differentiating uses of options like 'width' and 'height'
  36 # from appearances of identically-named options in CSS.
  37 def find_braces(txt):
  38   """Really primitive method to find text inside of {..} braces.
  39   Doesn't work if there's an unmatched brace in a string, e.g. '{'. """
  40   out = ''
  41   level = 0
  42   for char in txt:
  43     if char == '{':
  44       level += 1
  45     if level >= 1:
  46       out += char
  47     if char == '}':
  48       level -= 1
  49   return out
  50
  51 def search_files(type, files):
  52   # Find text followed by a colon. These won't all be options, but those that
  53   # have the same name as a Dygraph option probably will be.
  54   prop_re = re.compile(r'\b([a-zA-Z0-9]+) *:')
  55   for test_file in files:
  56     text = file(test_file).read()
  57     # Hack for slipping past gallery demos that have title in their attributes
  58     # so they don't appear as reasons for the demo to have 'title' options.
  59     if type == "gallery":
  60       idx = text.find("function(")
  61       if idx >= 0:
  62         text = text[idx:]
  63     braced_html = find_braces(text)
  64     if debug_tests:
  65       print braced_html
  66
  67     ms = re.findall(prop_re, braced_html)
  68     for opt in ms:
  69       if debug_tests: print '\n'.join(ms)
  70       if opt in docs and test_file not in docs[opt][type]:
  71         docs[opt][type].append(test_file)
  72
  73 search_files("tests", glob.glob("tests/*.html"))
  74 search_files("gallery", glob.glob("gallery/*.js")) #TODO add grep "Gallery.register\("
  75
  76 if debug_tests: sys.exit(0)
  77
  78 # Extract a labels list.
  79 labels = []
  80 for nu, opt in docs.iteritems():
  81   for label in opt['labels']:
  82     if label not in labels:
  83       labels.append(label)
  84
  85 print """<!DOCTYPE HTML>
  86 <html>
  87 <head>
  88   <title>Dygraphs Options Reference</title>
  89   <link rel="stylesheet" href="style.css">
  90   <style type="text/css">
  91     p.option {
  92       padding-left: 25px;
  93     }
  94     div.parameters {
  95       padding-left: 15px;
  96     }
  97     #nav {
  98       position: fixed;
  99     }
 100     #content {
 101       max-width: 800px;
 102     }
 103   </style>
 104 </head>
 105 <body>
 106 """
 107
 108 print """
 109 <div id='nav'>
 110 <h2>Dygraphs</h2>
 111 <ul>
 112   <li><a href="index.html">Home</a>
 113   <li><a href="data.html">Data Formats</a></li>
 114   <li><a href="annotations.html">Annotations</a></li>
 115 </ul>
 116 <h2>Options Reference</h2>
 117 <ul>
 118   <li><a href="#usage">Usage</a>
 119 """
 120 for label in sorted(labels):
 121   print '  <li><a href="#%s">%s</a>\n' % (label, label)
 122 print '</ul>\n</div>\n\n'
 123
 124 print """
 125 <div id='content'>
 126 <h2>Options Reference</h2>
 127 <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>
 128
 129 <a name="usage"></a><h3>Usage</h3>
 130 <p>You specify options in the third parameter to the dygraphs constructor:</p>
 131 <pre>g = new Dygraph(div,
 132                 data,
 133                 {
 134                   option1: value1,
 135                   option2: value2,
 136                   ...
 137                 });
 138 </pre>
 139
 140 <p>After you've created a Dygraph, you can change an option by calling the <code>updateOptions</code> method:</p>
 141 <pre>g.updateOptions({
 142                   new_option1: value1,
 143                   new_option2: value2
 144                 });
 145 </pre>
 146 <p>And, without further ado, here's the complete list of options:</p>
 147 """
 148
 149 def test_name(f):
 150   """Takes 'tests/demo.html' -> 'demo'"""
 151   return f.replace('tests/', '').replace('.html', '')
 152
 153 def gallery_name(f):
 154   """Takes 'gallery/demo.js' -> 'demo'"""
 155   return f.replace('gallery/', '').replace('.js', '')
 156
 157 def urlify_gallery(f):
 158   """Takes 'gallery/demo.js' -> 'demo'"""
 159   return f.replace('gallery/', 'gallery/#g/').replace('.js', '')
 160
 161
 162 for label in sorted(labels):
 163   print '<a name="%s"><h3>%s</h3>\n' % (label, label)
 164
 165   for opt_name in sorted(docs.keys()):
 166     opt = docs[opt_name]
 167     if label not in opt['labels']: continue
 168     tests = opt['tests']
 169     if not tests:
 170       examples_html = '<font color=red>NONE</font>'
 171     else:
 172       examples_html = ' '.join(
 173         '<a href="%s">%s</a>' % (f, test_name(f)) for f in tests)
 174
 175     gallery = opt['gallery']
 176     if not gallery:
 177       gallery_html = '<font color=red>NONE</font>'
 178     else:
 179       gallery_html = ' '.join(
 180         '<a href="%s">%s</a>' % (urlify_gallery(f), gallery_name(f)) for f in gallery)
 181
 182     if 'parameters' in opt:
 183       parameters = opt['parameters']
 184       parameters_html = '\n'.join("<i>%s</i>: %s<br/>" % (p[0], p[1]) for p in parameters)
 185       parameters_html = "\n  <div class='parameters'>\n%s</div>" % (parameters_html);
 186     else:
 187       parameters_html = ''
 188
 189     if not opt['type']: opt['type'] = '(missing)'
 190     if not opt['default']: opt['default'] = '(missing)'
 191     if not opt['description']: opt['description'] = '(missing)'
 192
 193     print """
 194   <div class='option'><a name="%(name)s"></a><b>%(name)s</b><br/>
 195   <p>%(desc)s</p>
 196   <i>Type: %(type)s</i><br/>%(parameters)s
 197   <i>Default: %(default)s</i></p>
 198   Gallery Samples: %(gallery_html)s<br/>
 199   Other Examples: %(examples_html)s<br/>
 200   <br/></div>
 201   """ % { 'name': opt_name,
 202           'type': opt['type'],
 203           'parameters': parameters_html,
 204           'default': opt['default'],
 205           'desc': opt['description'],
 206           'examples_html': examples_html,
 207           'gallery_html': gallery_html}
 208
 209
 210 print """
 211 <a name="point_properties"></a><h3>Point Properties</h3>
 212 Some callbacks take a point argument. Its properties are:<br/>
 213 <ul>
 214 <li>xval/yval: The data coordinates of the point (with dates/times as millis since epoch)</li>
 215 <li>canvasx/canvasy: The canvas coordinates at which the point is drawn.</li>
 216 <li>name: The name of the data series to which the point belongs</li>
 217 </ul>
 218 </div>
 219 </body>
 220 </html>
 221 """
 222
 223 # This page was super-helpful:
 224 # http://jsbeautifier.org/