add appcache generation to apidocs

lib/dartdoc/dartdoc.dart

 // Copyright (c) 2012, 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.
 
 /**
  * To generate docs for a library, run this script with the path to an
  * entrypoint .dart file, like:
  *
  *     $ dart dartdoc.dart foo.dart
  *
@@ skipping 40 matching lines @@
 /**
  * Run this from the `lib/dartdoc` directory.
  */
 void main() {
   final args = new Options().arguments;
 
   // Parse the dartdoc options.
   bool includeSource;
   int mode;
   String outputDir;
+  bool generateAppCache;
 
   for (int i = 0; i < args.length - 1; i++) {
     final arg = args[i];
 
     switch (arg) {
       case '--no-code':
         includeSource = false;
         break;
 
       case '--mode=static':
         mode = MODE_STATIC;
         break;
 
       case '--mode=live-nav':
         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);
         } else {
           print('Unknown option: $arg');
           return;
         }
         break;
     }
   }
@@ skipping 11 matching lines @@
   final compilerPath = joinPaths(frogPath, 'minfrog');
 
   parseOptions(frogPath, ['', '', '--libdir=$libDir'], files);
   initializeWorld(files);
 
   final dartdoc = new Dartdoc();
 
   if (includeSource != null) dartdoc.includeSource = includeSource;
   if (mode != null) dartdoc.mode = mode;
   if (outputDir != null) dartdoc.outputDir = outputDir;
+  if (generateAppCache != null) dartdoc.generateAppCache = generateAppCache;
 
   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');
+  final Future scriptCompiled = compileScript(compilerPath, libDir,
+                '$scriptDir/client-$clientScript.dart',
+                '${dartdoc.outputDir}/client-$clientScript.js');
 
-  copyFiles('$scriptDir/static', dartdoc.outputDir);
+  final 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 ' +
       '${dartdoc._totalMembers} members.');
 }
 
 /**
  * Gets the full path to the directory containing the entrypoint of the current
  * script. In other words, if you invoked dartdoc, directly, it will be the
  * path to the directory containing `dartdoc.dart`. If you're running a script
@@ skipping 15 matching lines @@
   outputDir.createSync();
 }
 
 /**
  * Copies all of the files in the directory [from] to [to]. Does *not*
  * recursively copy subdirectories.
  *
  * 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) {
+  final completer = new Completer();
   final fromDir = new Directory(from);
   fromDir.onFile = (path) {
     final name = basename(path);
     // TODO(rnystrom): Hackish. Ignore 'hidden' files like .DS_Store.
     if (name.startsWith('.')) return;
 
     new File(path).readAsBytes((bytes) {
       final outFile = new File('$to/$name');
       final stream = outFile.openOutputStream(FileMode.WRITE);
       stream.write(bytes, copyBuffer: false);
       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) {
+  final completer = new Completer();
   onExit(int exitCode, String stdout, String stderr) {
     if (exitCode != 0) {
       final message = 'Non-zero exit code from $compilerPath';
       print('$message.');
       print(stdout);
       print(stderr);
       throw message;
     }
+    completer.complete(true);
   }
 
   onError(error) {
     final message = 'Error trying to execute $compilerPath. Error: $error';
     print('$message.');
     throw message;
   }
 
   print('Compiling $dartPath to $jsPath');
   new Process.run(compilerPath, [
     '--libdir=$libDir', '--out=$jsPath',
     '--compile-only', '--enable-type-checks', '--warnings-as-errors',
     dartPath], null, onExit).onError = onError;
+  return completer.future;
 }
 
 class Dartdoc {
 
   /** Set to `false` to not include the source code in the generated docs. */
   bool includeSource = true;
 
   /**
    * Dartdoc can generate docs in a few different ways based on how dynamic you
    * want the client-side behavior to be. The value for this should be one of
    * the `MODE_` constants.
    */
   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';
 
   /**
    * The title used for the overall generated output. Set this to change it.
    */
   String mainTitle = 'Dart Documentation';
 
   /**
    * The URL that the Dart logo links to. Defaults "index.html", the main
@@ skipping 77 matching lines @@
         return a.name.toUpperCase().compareTo(b.name.toUpperCase());
       });
 
       // Generate the docs.
       if (mode == MODE_LIVE_NAV) docNavigationJson();
 
       docIndex();
       for (final library in _sortedLibraries) {
         docLibrary(library);
       }
+
+      if (generateAppCache) {
+        generateAppCacheManifest();
+      }
     } finally {
       options.dietParse = oldDietParse;
     }
   }
 
   void startFile(String path) {
     _filePath = path;
     _file = new StringBuffer();
   }
 
@@ skipping 23 matching lines @@
    * breadcrumbs are an interleaved list of links and titles. If a link is null,
    * then no link will be generated. For example, given:
    *
    *     ['foo', 'foo.html', 'bar', null]
    *
    * It will output:
    *
    *     <a href="foo.html">foo</a> &rsaquo; bar
    */
   void writeHeader(String title, List<String> breadcrumbs) {
+    final htmlAttributes = generateAppCache ?
+        'manifest="/appcache.manifest"' : '';
+    
     write(
         '''
         <!DOCTYPE html>
-        <html>
+        <html${htmlAttributes == '' ? '' : ' $htmlAttributes'}>
         <head>
         ''');
     writeHeadContents(title);
 
     // Add data attributes describing what the page documents.
     var data = '';
     if (_currentLibrary != null) {
       data += ' data-library="${md.escapeHtml(_currentLibrary.name)}"';
     }
 
@@ skipping 922 matching lines @@
     // * Type parameters of the enclosing type.
 
     return new md.Element.text('code', name);
   }
 
   // TODO(rnystrom): Move into SourceSpan?
   int getSpanColumn(SourceSpan span) {
     final line = span.file.getLine(span.start);
     return span.file.getColumn(line, span.start);
   }
+
+  generateAppCacheManifest() {
+    print('Generating app cache manifest from output $outputDir');
+    startFile('appcache.manifest');
+    write("CACHE MANIFEST\n\n");
+    write("# VERSION: ${new Date.now()}\n\n");
+    write("NETWORK:\n*\n\n");
+    write("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);
+      write("$relativePath\n");
+    };
+    toCache.onDone = (done) => endFile();
+    toCache.list(recursive: true);
+  }
 }