Add a mode to dartdoc to generate the navigation on the client.

utils/dartdoc/client-live-nav.dart

Index: utils/dartdoc/client-live-nav.dart
diff --git a/utils/dartdoc/client-live-nav.dart b/utils/dartdoc/client-live-nav.dart
new file mode 100644
index 0000000000000000000000000000000000000000..905f27833614656a42c8880b430762f4603e4815
--- /dev/null
+++ b/utils/dartdoc/client-live-nav.dart
@@ -0,0 +1,111 @@
+// Copyright (c) 2011, the Dart project authors.  Please see the AUTHORS file
+// for details. All rights reserved. Use of this source code is governed by a
+// BSD-style license that can be found in the LICENSE file.
+
+/** Provides client-side behavior for generated docs. */
+#library('client-live-nav');
+
+#import('dart:html');
+#import('dart:json');
+#import('../../frog/lang.dart', prefix: 'frog');
+#import('classify.dart');
+#import('markdown.dart', prefix: 'md');
+
+#source('client-shared.dart');
+
+// The names of the library and type that this page documents.
+String currentLibrary = null;
+String currentType = null;
+
+// What we need to prefix relative URLs with to get them to work.
+String prefix = '';
+
+main() {
+  window.on.contentLoaded.add((e) {
+    // Figure out where we are.
+    final body = document.query('body');
+    currentLibrary = body.attributes['data-library'];
+    currentType = body.attributes['data-type'];

[nweiz, 2012/01/19 19:20:17]

body.dataAttributes['type'] is slightly more idiomatic.

[Bob Nystrom, 2012/01/19 20:11:07]

Done.

+    prefix = (currentType != null) ? '../' : '';
+
+    enableCodeBlocks();
+
+    // Request the navigation data so we can build the HTML for it.
+    new XMLHttpRequest.getTEMPNAME('${prefix}nav.json', (request) {
+      buildNavigation(JSON.parse(request.responseText));
+    });
+  });
+}
+
+/** Turns [name] into something that's safe to use as a file name. */
+// TODO(bob): Copied from utils.dart. :(
+String sanitize(String name) => name.replaceAll(':', '_').replaceAll('/', '_');
+
+/**
+ * Takes [libraries], a JSON object representing a set of libraries and builds
+ * a string of HTML representation the navigation for those libraries, relative

[nweiz, 2012/01/19 19:20:17]

s/representation/representing/

[nweiz, 2012/01/19 19:20:17]

"builds a string of HTML" seems to imply that this will return a string. Maybe
instead say "inserts an HTML element"?

[Bob Nystrom, 2012/01/19 20:11:07]

Done. This comment was all kinds of out of date.

+ * to [currentLibrary] and [currentType] which describe the current page.
+ */
+buildNavigation(libraries) {
+  final libraryNames = libraries.getKeys();
+  libraryNames.sort((a, b) => a.compareTo(b));

[nweiz, 2012/01/19 19:20:17]

Off topic: this should really be the default argument to #sort.

[Bob Nystrom, 2012/01/19 20:11:07]

Yeah. Filed a bug: dartbug.com/1235

+
+  final html = new StringBuffer();
+  for (final libraryName in libraryNames) {
+    html.add('<h2><div class="icon-library"></div>');
+    if ((currentLibrary == libraryName) && (currentType == null)) {

[nweiz, 2012/01/19 19:20:17]

Style nit: redundant parens.

[Bob Nystrom, 2012/01/19 20:11:07]

I usually don't rely on operator precedence, but for you I will. Done.

+      html.add('<strong>$libraryName</strong>');

[nweiz, 2012/01/19 19:20:17]

How sure are we that libraryName will never contain any HTML-active characters?

[Bob Nystrom, 2012/01/19 20:11:07]

Pretty sure, but sanitized just in case.

+    } else {
+      final url = '$prefix${sanitize(libraryName)}.html';
+      html.add('<a href="$url">$libraryName</a>');
+    }
+    html.add('</h2>');
+
+    // Only list the types for the current library.
+    if (currentLibrary == libraryName) {
+      buildLibraryNavigation(html, libraries[libraryName]);
+    }
+  }
+
+  // Insert it into the DOM.
+  final navElement = document.query('.nav');
+  navElement.innerHTML = html.toString();
+}
+
+/** Writes the navigation for the types contained by [library] to [html]. */
+buildLibraryNavigation(StringBuffer html, library) {
+  // Show the exception types separately.
+  final types = [];
+  final exceptions = [];
+
+  for (final type in library) {
+    if (type['name'].endsWith('Exception')) {

[nweiz, 2012/01/19 19:20:17]

This seems a little hacky. Could you include an isException flag in the JSON
that's set based on whether the class extends Exception?

[Bob Nystrom, 2012/01/19 20:11:07]

It is a bit hacky, but I'm OK with that at least for now. I put this in because
corelib has such a huge number of exception types that they were cluttering up
the regular types, but I'm not crazy about having to do this. I'd rather corelib
be cleaned up.

I kind of like going by name because it isn't necessary to extend Exception in
order to be throwable in Dart. I like the idea of having dartdoc go by naming
convention instead.

+      exceptions.add(type);
+    } else {
+      types.add(type);
+    }
+  }
+
+  if ((types.length == 0) && (exceptions.length == 0)) return;

[nweiz, 2012/01/19 19:20:17]

Style nit: more redundant parens.

[Bob Nystrom, 2012/01/19 20:11:07]

Done.

+
+  writeType(String icon, type) {
+    html.add('<li>');
+    if (currentType == type['name']) {
+      html.add(
+          '<div class="icon-$icon"></div><strong>${type["name"]}</strong>');
+    } else {
+      html.add(
+          '''
+          <a href="$prefix${type["url"]}">
+            <div class="icon-$icon"></div>${type["name"]}
+          </a>
+          ''');
+    }
+    html.add('</li>');
+  }
+
+  html.add('<ul>');
+  types.forEach((type) => writeType(type['kind'], type));
+  exceptions.forEach((type) => writeType('exception', type));
+  html.add('</ul>');
+}