Add a snapshot for docgen and use it in the build

pkg/docgen/lib/docgen.dart

 // Copyright (c) 2013, 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.
 
 /// **docgen** is a tool for creating machine readable representations of Dart
 /// code metadata, including: classes, members, comments and annotations.
 ///
 /// docgen is run on a `.dart` file or a directory containing `.dart` files.
 ///
 ///      $ dart docgen.dart [OPTIONS] [FILE/DIR]
@@ skipping 24 matching lines @@
 import '../../../sdk/lib/_internal/libraries.dart';
 
 var logger = new Logger('Docgen');
 
 const DEFAULT_OUTPUT_DIRECTORY = 'docs';
 
 var _outputDirectory;
 
 const String USAGE = 'Usage: dart docgen.dart [OPTIONS] fooDir/barFile';
 
-
 List<String> skippedAnnotations = const [
     'metadata.DocsEditable', '_js_helper.JSName', '_js_helper.Creates',
     '_js_helper.Returns'];
 
+/// If we can't find the SDK introduction text, which will happen if running
+/// from a snapshot and using --parse-sdk or --include-sdk, then use this
+/// hard-coded version. This should be updated to be consistent with the text
+/// in docgen/doc/sdk-introduction.md
+const DEFAULT_SDK_INTRODUCTION = """
+Welcome to the Dart API reference documentation,
+covering the official Dart API libraries.
+Some of the most fundamental Dart libraries include:
+
+* [dart:core](#dart:core):
+  Core functionality such as strings, numbers, collections, errors,
+  dates, and URIs.
+* [dart:html](#dart:html):
+  DOM manipulation for web apps.
+* [dart:io](#dart:io):
+  I/O for command-line apps.
+
+Except for dart:core, you must import a library before you can use it.
+Here's an example of importing dart:html, dart:math, and a
+third popular library called
+[polymer.dart](http://www.dartlang.org/polymer-dart/):
+
+    import 'dart:html';
+    import 'dart:math';
+    import 'package:polymer/polymer.dart';
+
+Polymer.dart is an example of a library that isn't
+included in the Dart download,
+but is easy to get and update using the _pub package manager_.
+For information on finding, using, and publishing libraries (and more)
+with pub, see
+[pub.dartlang.org](http://pub.dartlang.org).
+
+The main site for learning and using Dart is
+[www.dartlang.org](http://www.dartlang.org).
+Check out these pages:
+
+  * [Dart homepage](http://www.dartlang.org)
+  * [Tutorials](http://www.dartlang.org/docs/tutorials/)
+  * [Programmer's Guide](http://www.dartlang.org/docs/)
+  * [Samples](http://www.dartlang.org/samples/)
+  * [A Tour of the Dart Libraries](http://www.dartlang.org/docs/dart-up-and-running/contents/ch03.html)
+
+This API reference is automatically generated from the source code in the
+[Dart project](https://code.google.com/p/dart/).
+If you'd like to contribute to this documentation, see
+[Contributing](https://code.google.com/p/dart/wiki/Contributing)
+and
+[Writing API Documentation](https://code.google.com/p/dart/wiki/WritingApiDocumentation).
+""";
+
 /// Set of libraries declared in the SDK, so libraries that can be accessed
 /// when running dart by default.
 Iterable<LibraryMirror> _sdkLibraries;
 
 /// The dart:core library, which contains all types that are always available
 /// without import.
 LibraryMirror _coreLibrary;
 
 /// Support for [:foo:]-style code comments to the markdown parser.
 List<markdown.InlineSyntax> markdownSyntaxes =
@@ skipping 25 matching lines @@
 ///
 /// [packageRoot] is the packages directory of the directory being analyzed.
 /// If [includeSdk] is `true`, then any SDK libraries explicitly imported will
 /// also be documented.
 /// If [parseSdk] is `true`, then all Dart SDK libraries will be documented.
 /// This option is useful when only the SDK libraries are needed.
 ///
 /// Returned Future completes with true if document generation is successful.
 Future<bool> docgen(List<String> files, {String packageRoot,
     bool outputToYaml: true, bool includePrivate: false, bool includeSdk: false,
-    bool parseSdk: false, bool append: false, String introduction: '',
+    bool parseSdk: false, bool append: false, String introFileName: '',
     out: DEFAULT_OUTPUT_DIRECTORY, List<String> excludeLibraries,
     bool includeDependentPackages}) {
   _excluded = excludeLibraries;
   _includePrivate = includePrivate;
   _outputDirectory = out;
   _includeDependentPackages = includeDependentPackages;
   if (!append) {
     var dir = new Directory(_outputDirectory);
     if (dir.existsSync()) dir.deleteSync(recursive: true);
   }
@@ skipping 32 matching lines @@
       var availableLibrariesByPath = new Map.fromIterables(
           availableLibraries.map((each) => each.uri),
           availableLibraries);
       var librariesToDocument = requestedLibraries.map(
           (each) => availableLibrariesByPath.putIfAbsent(each,
               () => throw "Missing library $each")).toList();
       librariesToDocument.addAll((includeSdk || parseSdk) ? _sdkLibraries : []);
       librariesToDocument.removeWhere((x) => _excluded.contains(x.simpleName));
       _documentLibraries(librariesToDocument, includeSdk: includeSdk,
           outputToYaml: outputToYaml, append: append, parseSdk: parseSdk,
-          introduction: introduction);
+          introFileName: introFileName);

[ricow1, 2014/01/13 13:14:20]

do we ever read this from a file now? if not just remove this argument here,
above and below

[Alan Knight, 2014/01/13 17:36:04]

We don't in the SDK, but if we're using this to generate docs for an individual
package we want them to be able to provide an introductory text.

       return true;
     });
 }
 
 /// All of the directories for our dependent packages
 List<String> allDependentPackageDirs(String packageDirectory) {
   var dependentsJson = Process.runSync('pub', ['list-package-dirs'],
       workingDirectory: packageDirectory, runInShell: true);
   if (dependentsJson.exitCode != 0) {
     print(dependentsJson.stderr);
@@ skipping 92 matching lines @@
 }
 
 String _findPackageRoot(String directory) {
   var files = listDir(directory, recursive: true);
   // Return '' means that there was no pubspec.yaml and therefor no packageRoot.
   String packageRoot = files.firstWhere((f) =>
       f.endsWith('${path.separator}pubspec.yaml'), orElse: () => '');
   if (packageRoot != '') {
     packageRoot = path.join(path.dirname(packageRoot), 'packages');
   }
-  return packageRoot;
+  return path.normalize(path.absolute(packageRoot));
 }
 
 /// Read a pubspec and return the library name.
 String _packageName(String pubspecName) {
   File pubspec = new File(pubspecName);
   if (!pubspec.existsSync()) return '';
   var contents = pubspec.readAsStringSync();
   var spec = loadYaml(contents);
   return spec["name"];
 }
@@ skipping 55 matching lines @@
         // Currently, a string is thrown when it fails to create a mirror
         // system, and it is not possible to use the stack trace. BUG(#11622)
         // To avoid printing the stack trace.
         exit(1);
       });
 }
 
 /// Creates documentation for filtered libraries.
 void _documentLibraries(List<LibraryMirror> libs, {bool includeSdk: false,
     bool outputToYaml: true, bool append: false, bool parseSdk: false,
-    String introduction: ''}) {
+    String introFileName: ''}) {
   libs.forEach((lib) {
     // Files belonging to the SDK have a uri that begins with 'dart:'.
     if (includeSdk || !lib.uri.toString().startsWith('dart:')) {
       var library = generateLibrary(lib);
       entityMap[library.name] = library;
     }
   });
   // After everything is created, do a pass through all classes to make sure no
   // intermediate classes created by mixins are included, all the links to
   // exported members point to the new library.
   entityMap.values.where((e) => e is Class).forEach(
       (c) => c.updateLinksAndRemoveIntermediaryClasses());
   // Everything is a subclass of Object, therefore empty the list to avoid a
   // giant list of subclasses to be printed out.
   if (includeSdk) (entityMap['dart-core.Object'] as Class).subclasses.clear();
 
   var filteredEntities = entityMap.values.where(_isVisible);
 
   // Outputs a JSON file with all libraries and their preview comments.
   // This will help the viewer know what libraries are available to read in.
   var libraryMap;
   var linkResolver = (name) => fixReference(name, null, null, null);
+
+  String readIntroductionFile(String fileName, includeSdk) {
+    var defaultText = includeSdk ? DEFAULT_SDK_INTRODUCTION : '';
+    var introText = defaultText;
+    if (fileName.isNotEmpty) {
+      var introFile = new File(fileName);
+      introText = introFile.existsSync() ? introFile.readAsStringSync() :
+          defaultText;
+    }
+    return markdown.markdownToHtml(introText,
+        linkResolver: linkResolver, inlineSyntaxes: markdownSyntaxes);
+  }
+
   if (append) {
     var docsDir = listDir(_outputDirectory);
     if (!docsDir.contains('$_outputDirectory/library_list.json')) {
       throw new StateError('No library_list.json');
     }
     libraryMap =
         JSON.decode(new File(
             '$_outputDirectory/library_list.json').readAsStringSync());
     libraryMap['libraries'].addAll(filteredEntities
         .where((e) => e is Library)
         .map((e) => e.previewMap));
-    if (introduction.isNotEmpty) {
-      var intro = libraryMap['introduction'];
-      if (intro.isNotEmpty) intro += '<br/><br/>';
-      intro += markdown.markdownToHtml(
-          new File(introduction).readAsStringSync(),
-              linkResolver: linkResolver, inlineSyntaxes: markdownSyntaxes);
-      libraryMap['introduction'] = intro;
-    }
+    var intro = libraryMap['introduction'];
+    var spacing = intro.isEmpty ? '' : '<br/><br/>';
+    libraryMap['introduction'] =
+        "$intro$spacing${readIntroductionFile(introFileName, includeSdk)}";
     outputToYaml = libraryMap['filetype'] == 'yaml';
   } else {
     libraryMap = {
       'libraries' : filteredEntities.where((e) =>
           e is Library).map((e) => e.previewMap).toList(),
-      'introduction' : introduction == '' ?
-          '' : markdown.markdownToHtml(new File(introduction)
-              .readAsStringSync(), linkResolver: linkResolver,
-                  inlineSyntaxes: markdownSyntaxes),
+      'introduction' : readIntroductionFile(introFileName, includeSdk),
       'filetype' : outputToYaml ? 'yaml' : 'json'
     };
   }
   _writeToFile(JSON.encode(libraryMap), 'library_list.json');
 
   // Output libraries and classes to file after all information is generated.
   filteredEntities.where((e) => e is Class || e is Library).forEach((output) {
     _writeIndexableToFile(output, outputToYaml);
   });
 
@@ skipping 1303 matching lines @@
 /// Remove statics from the map of inherited items before adding them.
 Map _filterStatics(Map items) {
   var result = {};
   items.forEach((name, item) {
     if (!item.isStatic) {
       result[name] = item;
     }
   });
   return result;
 }