X-Git-Url: https://adrianiainlam.tk/git/?a=blobdiff_plain;f=generate-documentation.py;h=1a66689371506fc59d0c4c180bb28e5af8757914;hb=846038aad4815feec55d2e86b8ccfad7dc1019b6;hp=5b6400f35b38710f63dae18fee99f3b41c8ae245;hpb=0e37f8e5b44d3e747be8ad87fa47cc734a630626;p=dygraphs.git
diff --git a/generate-documentation.py b/generate-documentation.py
index 5b6400f..1a66689 100755
--- a/generate-documentation.py
+++ b/generate-documentation.py
@@ -1,11 +1,22 @@
-#!/usr/bin/python
-import json
+#!/usr/bin/env python
+
+# Generate docs/options.html
+
import glob
+import json
+import os
import re
+import sys
+# Set this to the path to a test file to get debug output for just that test
+# file. Can be helpful to figure out why a test is not being shown for a
+# particular option.
+debug_tests = [] # [ 'tests/zoom.html' ]
+
+# Pull options reference JSON out of dygraph.js
js = ''
in_json = False
-for line in file('dygraph.js'):
+for line in file('dygraph-options-reference.js'):
if '' in line:
in_json = True
elif '' in line:
@@ -20,7 +31,10 @@ docs = json.loads(js)
# Go through the tests and find uses of each option.
for opt in docs:
docs[opt]['tests'] = []
+ docs[opt]['gallery'] = []
+# This is helpful for differentiating uses of options like 'width' and 'height'
+# from appearances of identically-named options in CSS.
def find_braces(txt):
"""Really primitive method to find text inside of {..} braces.
Doesn't work if there's an unmatched brace in a string, e.g. '{'. """
@@ -35,36 +49,179 @@ def find_braces(txt):
level -= 1
return out
-prop_re = re.compile(r'\b([a-zA-Z]+):')
-for test_file in glob.glob('tests/*.html'):
- braced_html = find_braces(file(test_file).read())
- ms = re.findall(prop_re, braced_html)
- for opt in ms:
- if opt in docs and test_file not in docs[opt]['tests']:
- docs[opt]['tests'].append(test_file)
+def search_files(type, files):
+ # Find text followed by a colon. These won't all be options, but those that
+ # have the same name as a Dygraph option probably will be.
+ prop_re = re.compile(r'\b([a-zA-Z0-9]+) *:')
+ for test_file in files:
+ if os.path.isfile(test_file): # Basically skips directories
+ text = file(test_file).read()
+
+ # Hack for slipping past gallery demos that have title in their attributes
+ # so they don't appear as reasons for the demo to have 'title' options.
+ if type == "gallery":
+ idx = text.find("function(")
+ if idx >= 0:
+ text = text[idx:]
+ braced_html = find_braces(text)
+ if debug_tests:
+ print braced_html
+
+ ms = re.findall(prop_re, braced_html)
+ for opt in ms:
+ if debug_tests: print '\n'.join(ms)
+ if opt in docs and test_file not in docs[opt][type]:
+ docs[opt][type].append(test_file)
+
+search_files("tests", glob.glob("tests/*.html"))
+search_files("gallery", glob.glob("gallery/*.js")) #TODO add grep "Gallery.register\("
+
+if debug_tests: sys.exit(0)
+
+# Extract a labels list.
+labels = []
+for nu, opt in docs.iteritems():
+ for label in opt['labels']:
+ if label not in labels:
+ labels.append(label)
+
+print """
+
+
+
+
Options Reference
+
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.
-def name(f):
+
Usage
+
You specify options in the third parameter to the dygraphs constructor:
+
g = new Dygraph(div,
+ data,
+ {
+ option1: value1,
+ option2: value2,
+ ...
+ });
+
+
+
After you've created a Dygraph, you can change an option by calling the updateOptions
method:
+
g.updateOptions({
+ new_option1: value1,
+ new_option2: value2
+ });
+
+
And, without further ado, here's the complete list of options:
+"""
+
+def test_name(f):
+ """Takes 'tests/demo.html' -> 'demo'"""
return f.replace('tests/', '').replace('.html', '')
-for opt_name in sorted(docs.keys()):
- opt = docs[opt_name]
- tests = opt['tests']
- if not tests:
- examples_html = '
NONE'
- else:
- examples_html = ' '.join(
- '
%s' % (f, name(f)) for f in tests)
-
- print """
-
%(name)s
-%(desc)s
-Type: %(type)s
-Default: %(default)s
-Examples: %(examples_html)s
-
-""" % { 'name': opt_name,
- 'type': opt['type'],
- 'default': opt['default'],
- 'desc': opt['description'],
- 'examples_html': examples_html}
+def gallery_name(f):
+ """Takes 'gallery/demo.js' -> 'demo'"""
+ return f.replace('gallery/', '').replace('.js', '')
+
+def urlify_gallery(f):
+ """Takes 'gallery/demo.js' -> 'demo'"""
+ return f.replace('gallery/', 'gallery/#g/').replace('.js', '')
+
+
+for label in sorted(labels):
+ print '%s
\n' % (label, label)
+
+ for opt_name in sorted(docs.keys()):
+ opt = docs[opt_name]
+ if label not in opt['labels']: continue
+ tests = opt['tests']
+ if not tests:
+ examples_html = 'NONE'
+ else:
+ examples_html = ' '.join(
+ '%s' % (f, test_name(f)) for f in tests)
+
+ gallery = opt['gallery']
+ if not gallery:
+ gallery_html = 'NONE'
+ else:
+ gallery_html = ' '.join(
+ '%s' % (urlify_gallery(f), gallery_name(f)) for f in gallery)
+
+ if 'parameters' in opt:
+ parameters = opt['parameters']
+ parameters_html = '\n'.join("%s: %s
" % (p[0], p[1]) for p in parameters)
+ parameters_html = "\n
\n%s
" % (parameters_html);
+ else:
+ parameters_html = ''
+
+ if not opt['type']: opt['type'] = '(missing)'
+ if not opt['default']: opt['default'] = '(missing)'
+ if not opt['description']: opt['description'] = '(missing)'
+
+ print """
+
%(name)s
+
%(desc)s
+
Type: %(type)s%(parameters)s
+
Default: %(default)s
+ Gallery Samples: %(gallery_html)s
+ Other Examples: %(examples_html)s
+
+ """ % { 'name': opt_name,
+ 'type': opt['type'],
+ 'parameters': parameters_html,
+ 'default': opt['default'],
+ 'desc': opt['description'],
+ 'examples_html': examples_html,
+ 'gallery_html': gallery_html}
+
+
+print """
+
Point Properties
+Some callbacks take a point argument. Its properties are:
+
+- xval/yval: The data coordinates of the point (with dates/times as millis since epoch)
+- canvasx/canvasy: The canvas coordinates at which the point is drawn.
+- name: The name of the data series to which the point belongs
+
+
+
+
+"""
+# This page was super-helpful:
+# http://jsbeautifier.org/