add appcache generation to apidocs

lib/dartdoc/dartdoc.dart

Index: lib/dartdoc/dartdoc.dart
diff --git a/lib/dartdoc/dartdoc.dart b/lib/dartdoc/dartdoc.dart
index 88a6c22ba3baa8e07bca7775b612c5a454163ded..33c32bb6c44b3c5470d39f1458cc75cff70f78b6 100644
--- a/lib/dartdoc/dartdoc.dart
+++ b/lib/dartdoc/dartdoc.dart
@@ -58,6 +58,7 @@ void main() {
   bool includeSource;
   int mode;
   String outputDir;
+  bool generateAppCache = false;

[Bob Nystrom, 2012/04/25 21:43:15]

Instead of setting this to false, just leave it null...

[sethladd, 2012/04/25 23:13:28]

OK, but why? In this case, false is the default

[Bob Nystrom, 2012/04/25 23:27:50]

I try to have a single canonical point of truth for most values. DRY?

 
   for (int i = 0; i < args.length - 1; i++) {
     final arg = args[i];
@@ -75,6 +76,11 @@ void main() {
         mode = MODE_LIVE_NAV;
         break;
 
+      case '--generate-app-cache':
+      case '--generate-app-cache=true':
+        generateAppCache = true;
+        break;
+
       default:
         if (arg.startsWith('--out=')) {
           outputDir = arg.substring('--out='.length);
@@ -106,17 +112,21 @@ void main() {
   if (includeSource != null) dartdoc.includeSource = includeSource;
   if (mode != null) dartdoc.mode = mode;
   if (outputDir != null) dartdoc.outputDir = outputDir;
+  dartdoc.generateAppCache = generateAppCache;

[Bob Nystrom, 2012/04/25 21:43:15]

...and then here, do the if(!= null) check. That way the default value for this
is only in the Dartdoc class and not in multiple places.

[sethladd, 2012/04/25 23:13:28]

Done.

 
   cleanOutputDirectory(dartdoc.outputDir);
 
   // Compile the client-side code to JS.
   final clientScript = (dartdoc.mode == MODE_STATIC) ? 'static' : 'live-nav';
-  compileScript(compilerPath, libDir, '$scriptDir/client-$clientScript.dart',
-               '${dartdoc.outputDir}/client-$clientScript.js');
+  Future scriptCompiled = compileScript(compilerPath, libDir,

[Bob Nystrom, 2012/04/25 21:43:15]

Just use "final" here and elsewhere. We don't usually type annotate our locals.

[sethladd, 2012/04/25 23:13:28]

Done.

+                '$scriptDir/client-$clientScript.dart',
+                '${dartdoc.outputDir}/client-$clientScript.js');
 
-  copyFiles('$scriptDir/static', dartdoc.outputDir);
+  Future filesCopied = copyFiles('$scriptDir/static', dartdoc.outputDir);
 
-  dartdoc.document(entrypoint);
+  Futures.wait([scriptCompiled, filesCopied]).then((_) {
+    dartdoc.document(entrypoint);
+  });
 
   print('Documented ${dartdoc._totalLibraries} libraries, ' +
       '${dartdoc._totalTypes} types, and ' +
@@ -152,7 +162,8 @@ void cleanOutputDirectory(String path) {
  * Note: runs asynchronously, so you won't see any files copied until after the
  * event loop has had a chance to pump (i.e. after `main()` has returned).
  */
-void copyFiles(String from, String to) {
+Future copyFiles(String from, String to) {
+  var completer = new Completer();

[Bob Nystrom, 2012/04/25 21:43:15]

This codebase generally uses "final" for single assignment locals, so I'd do
that here to be consistent.

(In the future, I think we may standardize on using "var" everywhere, but that
isn't in the style guide yet.)

[sethladd, 2012/04/25 23:13:28]

Done.

   final fromDir = new Directory(from);
   fromDir.onFile = (path) {
     final name = basename(path);
@@ -166,15 +177,18 @@ void copyFiles(String from, String to) {
       stream.close();
     });
   };
+  fromDir.onDone = (done) => completer.complete(true);
   fromDir.list(recursive: false);
+  return completer.future;
 }
 
 /**
  * Compiles the given Dart script to a JavaScript file at [jsPath] using the
  * Dart-to-JS compiler located at [compilerPath].
  */
-void compileScript(String compilerPath, String libDir,
+Future compileScript(String compilerPath, String libDir,
     String dartPath, String jsPath) {
+  var completer = new Completer();
   onExit(int exitCode, String stdout, String stderr) {
     if (exitCode != 0) {
       final message = 'Non-zero exit code from $compilerPath';
@@ -183,6 +197,7 @@ void compileScript(String compilerPath, String libDir,
       print(stderr);
       throw message;
     }
+    completer.complete(true);
   }
 
   onError(error) {
@@ -196,6 +211,7 @@ void compileScript(String compilerPath, String libDir,
     '--libdir=$libDir', '--out=$jsPath',
     '--compile-only', '--enable-type-checks', '--warnings-as-errors',
     dartPath], null, onExit).onError = onError;
+  return completer.future;
 }
 
 class Dartdoc {
@@ -210,6 +226,11 @@ class Dartdoc {
    */
   int mode = MODE_LIVE_NAV;
 
+  /**
+   * Generates the App Cache manifest file, enabling offline doc viewing.
+   */
+  bool generateAppCache = false;
+
   /** Path to generate HTML files into. */
   String outputDir = 'docs';
 
@@ -307,6 +328,10 @@ class Dartdoc {
       for (final library in _sortedLibraries) {
         docLibrary(library);
       }
+
+      if (generateAppCache) {
+        generateAppCacheManifest();
+      }
     } finally {
       options.dietParse = oldDietParse;
     }
@@ -350,10 +375,12 @@ class Dartdoc {
    *     <a href="foo.html">foo</a> &rsaquo; bar
    */
   void writeHeader(String title, List<String> breadcrumbs) {
+    var htmlAttributes = generateAppCache ? 'manifest="/appcache.manifest"' : '';

[Bob Nystrom, 2012/04/25 21:43:15]

Long line.

[sethladd, 2012/04/25 23:13:28]

Done.

[Bob Nystrom, 2012/04/25 23:27:50]

"final" too. :)

[sethladd, 2012/05/29 16:03:55]

Done.

+    
     write(
         '''
         <!DOCTYPE html>
-        <html>
+        <html${htmlAttributes == '' ? '' : ' $htmlAttributes'}>
         <head>
         ''');
     writeHeadContents(title);
@@ -1296,4 +1323,26 @@ class Dartdoc {
     final line = span.file.getLine(span.start);
     return span.file.getColumn(line, span.start);
   }
+
+  generateAppCacheManifest() {
+    print('Generating app cache manifest from output $outputDir');
+    var manifestFile = new File('$outputDir/appcache.manifest');

[Bob Nystrom, 2012/04/25 21:43:15]

Can you use the file writing API dartdoc provides here? It's much more pleasant.

[sethladd, 2012/04/25 23:13:28]

sure, but as a new developer working on this code, that API wasn't obvious. new
developers now have to understand a proprietary API. it's also not documented.

for instance, endFile() includes the $outputDir. I had to read the method to
know that.

[Bob Nystrom, 2012/04/25 23:27:50]

Well, you do have to learn the codebase you work in at least somewhat. write()
etl. al. are used pervasively in this file.
Right, but that's kind of what dartdoc is. It writes files and it has code
already to make that easier. Why not use it consistently?
Sorry. :( I don't see any docs on this method either. ;)

I inherited this from a hacked-together sample script so it still needs polish.
:(

[sethladd, 2012/05/29 16:03:55]

touché! :)

+    var writer = manifestFile.openOutputStream(FileMode.WRITE);
+    writer.writeString("CACHE MANIFEST\n\n");
+    writer.writeString("# VERSION: ${new Date.now()}\n\n");
+    writer.writeString("NETWORK:\n*\n\n");
+    writer.writeString("CACHE:\n");
+    var toCache = new Directory(outputDir);
+    var pathPrefix = new File(outputDir).fullPathSync();
+    var pathPrefixLength = pathPrefix.length;
+    toCache.onFile = (filename) {
+      if (filename.endsWith('appcache.manifest')) {
+        return;
+      }
+      var relativePath = filename.substring(pathPrefixLength + 1);
+      writer.writeString("$relativePath\n");
+    };
+    toCache.onDone = (done) => writer.close();
+    toCache.list(recursive: true);
+  }
 }