X-Git-Url: https://adrianiainlam.tk/git/?a=blobdiff_plain;f=generate-documentation.py;h=f6d7d7903c6ec8036c62d2d8ee83610f66ec95b2;hb=7e64db422edd4fb5ce6b5abfb668d23ec9d001b8;hp=3e88088e6e510cf96b4a0a44c281e427cb8d4a51;hpb=5af2de242af305c2d17d5316f52ea7316bad67f3;p=dygraphs.git diff --git a/generate-documentation.py b/generate-documentation.py index 3e88088..f6d7d79 100755 --- a/generate-documentation.py +++ b/generate-documentation.py @@ -1,12 +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: @@ -21,6 +31,7 @@ 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. @@ -38,70 +49,72 @@ def find_braces(txt): level -= 1 return out -# 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 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 _, opt in docs.iteritems(): for label in opt['labels']: if label not in labels: labels.append(label) print """ - - - Dygraphs Options Reference - - - - + + + + + + """ print """ -\n\n' 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.

-

Usage

-

You specify options in the third parameter to the dygraphs constructor: +

Usage

+

You specify options in the third parameter to the dygraphs constructor:

g = new Dygraph(div,
                 data,
                 {
@@ -111,15 +124,31 @@ print """
                 });
-After you've created a Dygraph, you can change an option by calling the updateOptions method: +

After you've created a Dygraph, you can change an option by calling the updateOptions method:

g.updateOptions({
                   new_option1: value1,
                   new_option2: value2
                 });
+

Some options can be set on a per-axis and per-series basis. See the docs on per-axis and per-series options to learn how to do this. The options which may be set in this way are marked as such on this page.

+

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', '') + +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) @@ -131,30 +160,54 @@ for label in sorted(labels): examples_html = 'NONE' else: examples_html = ' '.join( - '%s' % (f, name(f)) for f in tests) + '%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
- Default: %(default)s
- Examples: %(examples_html)s
-
+

%(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} + 'examples_html': examples_html, + 'gallery_html': gallery_html} print """ -
- - +

Point Properties

+Some callbacks take a point argument. Its properties are:
+ +
+ + """ # This page was super-helpful: