Generate docgen output along with api_docs as part of the build

pkg/docgen/lib/docgen.dart

Index: pkg/docgen/lib/docgen.dart
diff --git a/pkg/docgen/lib/docgen.dart b/pkg/docgen/lib/docgen.dart
index 8f48f5f53e3aadab4eb24df5ebd85d34e203ad33..6590416beb3080663154ba11346f8a94538e8e91 100644
--- a/pkg/docgen/lib/docgen.dart
+++ b/pkg/docgen/lib/docgen.dart
@@ -36,6 +36,8 @@ import '../../../sdk/lib/_internal/libraries.dart';
 
 var logger = new Logger('Docgen');
 
+var outputDirectory = 'docs';
+
 const String USAGE = 'Usage: dart docgen.dart [OPTIONS] fooDir/barFile';
 
 
@@ -74,6 +76,10 @@ Map<String, Indexable> entityMap = new Map<String, Indexable>();
 /// This is set from the command line arguments flag --include-private
 bool _includePrivate = false;
 
+/// Library names to explicitly exclude. Set from the command line option
+/// --exclude-lib

[Bob Nystrom, 2013/11/14 22:43:04]

"."

Also, current doc comment convention is that the first sentence should be on its
own:

/// Library names to explicitly exclude.
///
/// Set from the command line option --exclude-lib

[Alan Knight, 2013/11/15 18:49:56]

Done.

+List<String> _excluded;
+
 // TODO(janicejl): Make MDN content generic or pluggable. Maybe move
 // MDN-specific code to its own library that is imported into the default impl?
 /// Map of all the comments for dom elements from MDN.
@@ -91,10 +97,13 @@ Map _mdn;
 /// 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 introduction: '',
+    out: 'docs', List<String> excludeLibraries}) {
+  _excluded = excludeLibraries;
   _includePrivate = includePrivate;
+  outputDirectory = out;
   if (!append) {
-    var dir = new Directory('docs');
+    var dir = new Directory(outputDirectory);
     if (dir.existsSync()) dir.deleteSync(recursive: true);
   }
 
@@ -110,13 +119,14 @@ Future<bool> docgen(List<String> files, {String packageRoot,
   logger.info('Package Root: ${packageRoot}');
   linkResolver = (name) =>
       fixReference(name, _currentLibrary, _currentClass, _currentMember);
+  var librariesWeAskedFor = !parseSdk ? _listLibraries(files) : _listSdk();

[Bob Nystrom, 2013/11/14 22:43:04]

"We" seems funny to me. How about "requestedLibraries"?

[Alan Knight, 2013/11/15 18:49:56]

Done.

 
-  return getMirrorSystem(files, packageRoot: packageRoot, parseSdk: parseSdk)
+  return getMirrorSystem(librariesWeAskedFor, packageRoot: packageRoot,
+      parseSdk: parseSdk)
     .then((MirrorSystem mirrorSystem) {
       if (mirrorSystem.libraries.isEmpty) {
         throw new StateError('No library mirrors were created.');
       }
-      var librariesWeAskedFor = _listLibraries(files);
       var librariesWeGot = mirrorSystem.libraries.values.where(
           (each) => each.uri.scheme == 'file');
       _sdkLibraries = mirrorSystem.libraries.values.where(
@@ -130,6 +140,7 @@ Future<bool> docgen(List<String> files, {String packageRoot,
           (each) => librariesWeGotByPath.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);
@@ -178,7 +189,6 @@ String _packageIntro(packageDir) {
   return contents;
 }
 
-
 List<String> _listLibraries(List<String> args) {
   var libraries = new List<String>();
   for (var arg in args) {
@@ -218,7 +228,7 @@ List<String> _listDartFromDir(String args) {
       }
     }
   });
-  return libraries;
+  return libraries.map((each) => path.normalize(path.absolute(each))).toList();

[Bob Nystrom, 2013/11/14 22:43:04]

Could also do:

libraries.map(path.absolute).map(path.normalize).toList()

I'm not sure which I prefer. <shrug>

[Alan Knight, 2013/11/15 18:49:56]

I like yours better. Done.

 }
 
 String _findPackageRoot(String directory) {
@@ -254,9 +264,8 @@ List<String> _listSdk() {
 
 /// Analyzes set of libraries by getting a mirror system and triggers the
 /// documentation of the libraries.
-Future<MirrorSystem> getMirrorSystem(List<String> args, {String packageRoot,
-    bool parseSdk: false}) {
-  var libraries = !parseSdk ? _listLibraries(args) : _listSdk();
+Future<MirrorSystem> getMirrorSystem(List<String> 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.
 
@@ -331,12 +340,12 @@ void _documentLibraries(List<LibraryMirror> libs, {bool includeSdk: false,
   // This will help the viewer know what libraries are available to read in.
   var libraryMap;
   if (append) {
-    var docsDir = listDir('docs');
-    if (!docsDir.contains('docs/library_list.json')) {
+    var docsDir = listDir(outputDirectory);
+    if (!docsDir.contains('$outputDirectory/library_list.json')) {
       throw new StateError('No library_list.json');
     }
     libraryMap =
-        JSON.decode(new File('docs/library_list.json').readAsStringSync());
+        JSON.decode(new File('$outputDirectory/library_list.json').readAsStringSync());
     libraryMap['libraries'].addAll(filteredEntities
         .where((e) => e is Library)
         .map((e) => e.previewMap));
@@ -377,7 +386,7 @@ void _documentLibraries(List<LibraryMirror> libs, {bool includeSdk: false,
       filteredEntities.map((e) => e.typeName));
   if (append) {
     var previousIndex =
-        JSON.decode(new File('docs/index.json').readAsStringSync());
+        JSON.decode(new File('$outputDirectory/index.json').readAsStringSync());
     index.addAll(previousIndex);
   }
   _writeToFile(JSON.encode(index), 'index.json');
@@ -772,21 +781,21 @@ List<Type> _typeGenerics(TypeMirror mirror) {
   return [];
 }
 
-/// Writes text to a file in the 'docs' directory.
+/// Writes text to a file in the output directory.
 void _writeToFile(String text, String filename, {bool append: false}) {
-  Directory dir = new Directory('docs');
+  Directory dir = new Directory(outputDirectory);
   if (!dir.existsSync()) {
     dir.createSync();
   }
   // We assume there's a single extra level of directory structure for packages.
   if (path.split(filename).length > 1) {
-    var subdir = new Directory(path.join('docs', path.dirname(filename)));
+    var subdir = new Directory(path.join(outputDirectory, path.dirname(filename)));
     if (!subdir.existsSync()) {
       subdir.createSync();
     }
   }
 
-  File file = new File('docs/$filename');
+  File file = new File('$outputDirectory/$filename');

[Bob Nystrom, 2013/11/14 22:43:04]

Since you're using path.join() a few lines up, let's use it here too.

[Alan Knight, 2013/11/15 18:49:56]

Done.

   if (!file.existsSync()) {
     file.createSync();
   }