generate-documentation.py

   1 #!/usr/bin/env python
   2
   3 # Generate docs/options.html
   4
   5 import glob
   6 import json
   7 import os
   8 import re
   9 import sys
  10
  11 # Set this to the path to a test file to get debug output for just that test
  12 # file. Can be helpful to figure out why a test is not being shown for a
  13 # particular option.
  14 debug_tests = []  # [ 'tests/zoom.html' ]
  15
  16 # Pull options reference JSON out of dygraph.js
  17 js = ''
  18 in_json = False
  19 for line in file('dygraph-options-reference.js'):
  20   if '<JSON>' in line:
  21     in_json = True
  22   elif '</JSON>' in line:
  23     in_json = False
  24   elif in_json:
  25     js += line
  26
  27 # TODO(danvk): better errors here.
  28 assert js
  29 docs = json.loads(js)
  30
  31 # Go through the tests and find uses of each option.
  32 for opt in docs:
  33   docs[opt]['tests'] = []
  34   docs[opt]['gallery'] = []
  35
  36 # This is helpful for differentiating uses of options like 'width' and 'height'
  37 # from appearances of identically-named options in CSS.
  38 def find_braces(txt):
  39   """Really primitive method to find text inside of {..} braces.
  40   Doesn't work if there's an unmatched brace in a string, e.g. '{'. """
  41   out = ''
  42   level = 0
  43   for char in txt:
  44     if char == '{':
  45       level += 1
  46     if level >= 1:
  47       out += char
  48     if char == '}':
  49       level -= 1
  50   return out
  51
  52 def search_files(type, files):
  53   # Find text followed by a colon. These won't all be options, but those that
  54   # have the same name as a Dygraph option probably will be.
  55   prop_re = re.compile(r'\b([a-zA-Z0-9]+) *:')
  56   for test_file in files:
  57     if os.path.isfile(test_file): # Basically skips directories
  58       text = file(test_file).read()
  59
  60       # Hack for slipping past gallery demos that have title in their attributes
  61       # so they don't appear as reasons for the demo to have 'title' options.
  62       if type == "gallery":
  63         idx = text.find("function(")
  64         if idx >= 0:
  65           text = text[idx:]
  66       braced_html = find_braces(text)
  67       if debug_tests:
  68         print braced_html
  69
  70       ms = re.findall(prop_re, braced_html)
  71       for opt in ms:
  72         if debug_tests: print '\n'.join(ms)
  73         if opt in docs and test_file not in docs[opt][type]:
  74           docs[opt][type].append(test_file)
  75
  76 search_files("tests", glob.glob("tests/*.html"))
  77 search_files("gallery", glob.glob("gallery/*.js")) #TODO add grep "Gallery.register\("
  78
  79 if debug_tests: sys.exit(0)
  80
  81 # Extract a labels list.
  82 labels = []
  83 for _, opt in docs.iteritems():
  84   for label in opt['labels']:
  85     if label not in labels:
  86       labels.append(label)
  87
  88 print """
  89 <!--#include virtual="header.html" -->
  90
  91 <!--
  92   DO NOT EDIT THIS FILE!
  93
  94   This file is generated by generate-documentation.py.
  95 -->
  96
  97 <link rel=stylesheet href="options.css" />
  98
  99 """
 100
 101 print """
 102 <div class="col-lg-3">
 103 <div class="dygraphs-side-nav affix-top" data-spy="affix" data-offset-top="0">
 104 <ul class='nav'>
 105   <li><a href="#usage">Usage</a>
 106 """
 107 for label in sorted(labels):
 108   print '  <li><a href="#%s">%s</a>\n' % (label, label)
 109 print '</ul></div></div>\n\n'
 110
 111 print """
 112 <div id='content' class='col-lg-9'>
 113 <h2>Options Reference</h2>
 114 <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>
 115
 116 <a name="usage"></a><h3>Usage</h3>
 117 <p>You specify options in the third parameter to the dygraphs constructor:</p>
 118 <pre>g = new Dygraph(div,
 119                 data,
 120                 {
 121                   option1: value1,
 122                   option2: value2,
 123                   ...
 124                 });
 125 </pre>
 126
 127 <p>After you've created a Dygraph, you can change an option by calling the <code>updateOptions</code> method:</p>
 128 <pre>g.updateOptions({
 129                   new_option1: value1,
 130                   new_option2: value2
 131                 });
 132 </pre>
 133
 134 <p>Some options can be set on a per-axis and per-series basis. See the docs on <a href="per-axis.html">per-axis and per-series options</a> to learn how to do this. The options which may be set in this way are marked as such on this page.</p>
 135
 136 <p>For options which are functions (e.g. callbacks and formatters), the value of <code>this</code> is set to the Dygraph object.</p>
 137
 138 <p>And, without further ado, here's the complete list of options:</p>
 139 """
 140
 141 def test_name(f):
 142   """Takes 'tests/demo.html' -> 'demo'"""
 143   return f.replace('tests/', '').replace('.html', '')
 144
 145 def gallery_name(f):
 146   """Takes 'gallery/demo.js' -> 'demo'"""
 147   return f.replace('gallery/', '').replace('.js', '')
 148
 149 def urlify_gallery(f):
 150   """Takes 'gallery/demo.js' -> 'demo'"""
 151   return f.replace('gallery/', 'gallery/#g/').replace('.js', '')
 152
 153
 154 for label in sorted(labels):
 155   print '<a name="%s"></a><h3>%s</h3>\n' % (label, label)
 156
 157   for opt_name in sorted(docs.keys()):
 158     opt = docs[opt_name]
 159     if label not in opt['labels']: continue
 160     tests = opt['tests']
 161     if not tests:
 162       examples_html = '<font color=red>NONE</font>'
 163     else:
 164       examples_html = ' '.join(
 165         '<a href="%s">%s</a>' % (f, test_name(f)) for f in tests)
 166
 167     gallery = opt['gallery']
 168     if not gallery:
 169       gallery_html = '<font color=red>NONE</font>'
 170     else:
 171       gallery_html = ' '.join(
 172         '<a href="%s">%s</a>' % (urlify_gallery(f), gallery_name(f)) for f in gallery)
 173
 174     if 'parameters' in opt:
 175       parameters = opt['parameters']
 176       parameters_html = '\n'.join("<i>%s</i>: %s<br/>" % (p[0], p[1]) for p in parameters)
 177       parameters_html = "\n  <div class='parameters'>\n%s</div>" % (parameters_html);
 178     else:
 179       parameters_html = ''
 180
 181     if not opt['type']: opt['type'] = '(missing)'
 182     if not opt['default']: opt['default'] = '(missing)'
 183     if not opt['description']: opt['description'] = '(missing)'
 184
 185     print """
 186   <div class='option'><a name="%(name)s"></a><b>%(name)s</b>
 187   <a class="link" href="#%(name)s">#</a>
 188   <br/>
 189   <p>%(desc)s</p>
 190   <i>Type: %(type)s</i><br/>%(parameters)s
 191   <i>Default: %(default)s</i></p>
 192   Gallery Samples: %(gallery_html)s<br/>
 193   Other Examples: %(examples_html)s<br/>
 194   <br/></div>
 195   """ % { 'name': opt_name,
 196           'type': opt['type'],
 197           'parameters': parameters_html,
 198           'default': opt['default'],
 199           'desc': opt['description'],
 200           'examples_html': examples_html,
 201           'gallery_html': gallery_html}
 202
 203
 204 print """
 205 <a name="point_properties"></a><h3>Point Properties</h3>
 206 Some callbacks take a point argument. Its properties are:<br/>
 207 <ul>
 208 <li>xval/yval: The data coordinates of the point (with dates/times as millis since epoch)</li>
 209 <li>canvasx/canvasy: The canvas coordinates at which the point is drawn.</li>
 210 <li>name: The name of the data series to which the point belongs</li>
 211 <li>idx: The row number of the point in the data set</li>
 212 </ul>
 213 </div> <!-- #content -->
 214
 215 <!--#include virtual="footer.html" -->
 216 """
 217
 218 # This page was super-helpful:
 219 # http://jsbeautifier.org/