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..dd510cf2f485cb21d6c2004875aea980e592ac8f 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';

[kustermann, 2013/11/18 09:57:08]

Why are some other global variables a few lines down marked with an "_" (i.e.
library private) and this one is not?

Will these variables be accessed from somewher else?

[Alan Knight, 2013/11/18 20:34:50]

Made it private.

+
 const String USAGE = 'Usage: dart docgen.dart [OPTIONS] fooDir/barFile';
 
 
@@ -74,6 +76,12 @@ 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.
+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 +99,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}) {

[kustermann, 2013/11/18 09:57:08]

It's slightly strange that we have the default value 'docs' here *and* at line
39 (i.e. for the global outputDirectory variable).

[Alan Knight, 2013/11/18 20:34:50]

Yes. I can't default the parameter to a variable value, but made a constant and
defaulted it to that. Removed the default value for the variable, as it is
always and only ever initialized in this call.

+  _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,26 +121,28 @@ Future<bool> docgen(List<String> files, {String packageRoot,
   logger.info('Package Root: ${packageRoot}');
   linkResolver = (name) =>
       fixReference(name, _currentLibrary, _currentClass, _currentMember);
+  var requestedLibraries = !parseSdk ? _listLibraries(files) : _listSdk();
 
-  return getMirrorSystem(files, packageRoot: packageRoot, parseSdk: parseSdk)
+  return getMirrorSystem(requestedLibraries, 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(
+      var availableLibraries = mirrorSystem.libraries.values.where(
           (each) => each.uri.scheme == 'file');
       _sdkLibraries = mirrorSystem.libraries.values.where(
           (each) => each.uri.scheme == 'dart');
       _coreLibrary = _sdkLibraries.singleWhere((lib) =>
           lib.uri.toString().startsWith('dart:core'));
-      var librariesWeGotByPath = new Map.fromIterables(
-          librariesWeGot.map((each) => each.uri.toFilePath()),
-          librariesWeGot);
-      var librariesToDocument = librariesWeAskedFor.map(
-          (each) => librariesWeGotByPath.putIfAbsent(each,
+      var availableLibrariesByPath = new Map.fromIterables(
+          availableLibraries.map((each) => each.uri.toFilePath()),
+          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);
@@ -178,7 +191,6 @@ String _packageIntro(packageDir) {
   return contents;
 }
 
-
 List<String> _listLibraries(List<String> args) {
   var libraries = new List<String>();
   for (var arg in args) {
@@ -218,7 +230,7 @@ List<String> _listDartFromDir(String args) {
       }
     }
   });
-  return libraries;
+  return libraries.map(path.absolute).map(path.normalize).toList();
 }
 
 String _findPackageRoot(String directory) {
@@ -254,9 +266,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 +342,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 +388,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,24 +783,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');
+  if (text == null) return;
+  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');
-  if (!file.existsSync()) {
-    file.createSync();
-  }
+  File file = new File(path.join(outputDirectory, filename));
   file.writeAsStringSync(text, mode: append ? FileMode.APPEND : FileMode.WRITE);
 }