Let users specify the start page of the resulting docs

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 100 matching lines @@
 /// 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 introFileName: '',
     out: _DEFAULT_OUTPUT_DIRECTORY, List<String> excludeLibraries : const [],
-    bool includeDependentPackages: false}) {
+    bool includeDependentPackages: false, startPage}) {
   return _Generator.generateDocumentation(files, packageRoot: packageRoot,
       outputToYaml: outputToYaml, includePrivate: includePrivate,
       includeSdk: includeSdk, parseSdk: parseSdk, append: append,
       introFileName: introFileName, out: out,
       excludeLibraries: excludeLibraries,
-      includeDependentPackages: includeDependentPackages);
+      includeDependentPackages: includeDependentPackages,
+      startPage: startPage);
 }
 
 /// Analyzes set of libraries by getting a mirror system and triggers the
 /// documentation of the libraries.
 Future<MirrorSystem> getMirrorSystem(List<Uri> libraries,
     {String packageRoot, bool parseSdk: false}) {
   if (libraries.isEmpty) throw new StateError('No Libraries.');
 
   // Finds the root of SDK library based off the location of docgen.
   var root = _Generator._rootDirectory;
@@ skipping 94 matching lines @@
   /// 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.
   static Future<bool> generateDocumentation(List<String> files,
       {String packageRoot, bool outputToYaml: true, bool includePrivate: false,
        bool includeSdk: false, bool parseSdk: false, bool append: false,
        String introFileName: '', out: _DEFAULT_OUTPUT_DIRECTORY,
        List<String> excludeLibraries : const [],
-       bool includeDependentPackages: false}) {
+       bool includeDependentPackages: false, startPage}) {
     _excluded = excludeLibraries;
     _includePrivate = includePrivate;
     logger.onRecord.listen((record) => print(record.message));
 
     _ensureOutputDirectory(out, append);
     var updatedPackageRoot = _obtainPackageRoot(packageRoot, parseSdk, files);
 
     var requestedLibraries = _findLibrariesToDocument(files,
         includeDependentPackages);
 
@@ skipping 17 matching lines @@
             availableLibraries);
         var librariesToDocument = requestedLibraries.map(
             (each) => availableLibrariesByPath.putIfAbsent(each,
                 () => throw "Missing library $each")).toList();
         librariesToDocument.addAll(
             (includeSdk || parseSdk) ? Indexable._sdkLibraries : []);
         librariesToDocument.removeWhere(
             (x) => _excluded.contains(dart2js_util.nameOf(x)));
         _documentLibraries(librariesToDocument, includeSdk: includeSdk,
             outputToYaml: outputToYaml, append: append, parseSdk: parseSdk,
-            introFileName: introFileName);
+            introFileName: introFileName, startPage: startPage);
         return true;
       });
   }
 
   /// Writes [text] to a file in the output directory.
   static void _writeToFile(String text, String filename, {bool append: false}) {
     if (text == null) return;
     Directory dir = new Directory(_outputDirectory);
     if (!dir.existsSync()) {
       dir.createSync();
@@ skipping 12 matching lines @@
       }
     }
     File file = new File(path.join(_outputDirectory, filename));
     file.writeAsStringSync(text,
         mode: append ? FileMode.APPEND : FileMode.WRITE);
   }
 
   /// Creates documentation for filtered libraries.
   static void _documentLibraries(List<LibraryMirror> libs,
       {bool includeSdk: false, bool outputToYaml: true, bool append: false,
-       bool parseSdk: false, String introFileName: ''}) {
+       bool parseSdk: false, String introFileName: '', startPage}) {
     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;
       }
     });
 
     var filteredEntities = entityMap.values.where(_isFullChainVisible);
 
@@ skipping 51 matching lines @@
           "$intro$spacing${readIntroductionFile(introFileName, includeSdk)}";
       outputToYaml = libraryMap['filetype'] == 'yaml';
     } else {
       libraryMap = {
         'libraries' : filteredEntities.where((e) =>
             e is Library).map((e) => e.previewMap).toList(),
         'introduction' : readIntroductionFile(introFileName, includeSdk),
         'filetype' : outputToYaml ? 'yaml' : 'json'
       };
     }
+    if (startPage != null) libraryMap['startPage'] = startPage;
     _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);
     });
 
     // Outputs all the qualified names documented with their type.
     // This will help generate search results.
     _writeToFile(filteredEntities.map((e) =>
@@ skipping 1598 matching lines @@
         .map((e) => originalMirror.getField(e.simpleName).reflectee)
         .where((e) => e != null)
         .toList();
   }
 
   Map toMap() => {
     'name': Indexable.getDocgenObject(mirror, owningLibrary).docName,
     'parameters': parameters
   };
 }