Version 1.2.0-dev.5.2

dart/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 88 matching lines @@
 """;
 
 /// Docgen constructor initializes the link resolver for markdown parsing.
 /// Also initializes the command line arguments.
 ///
 /// [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.
+/// If [compile] is `true`, then after generating the documents, compile the
+/// viewer with dart2js.
 /// If [serve] is `true`, then after generating the documents we fire up a
 /// simple server to view the documentation.
 ///
 /// 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 serve: false,
-    bool noDocs: false, String startPage}) {
+    bool includeDependentPackages: false, bool compile: false, bool serve: false,
+    bool noDocs: false, String startPage, 
+    String pubScript, String dartBinary}) {
   var result;
   if (!noDocs) {
     _Viewer.ensureMovedViewerCode();
     result = _Generator.generateDocumentation(files, packageRoot: packageRoot,
         outputToYaml: outputToYaml, includePrivate: includePrivate,
         includeSdk: includeSdk, parseSdk: parseSdk, append: append,
         introFileName: introFileName, out: out,
         excludeLibraries: excludeLibraries,
         includeDependentPackages: includeDependentPackages,
-        startPage: startPage);
+        startPage: startPage, pubScript: pubScript, dartBinary: dartBinary);
     _Viewer.addBackViewerCode();
-    if (serve) {
+    if (compile || serve) {
       result.then((success) {
         if (success) {
-          _Viewer._cloneAndServe();
+          _createViewer(serve);
         }
       });
-    }
-  } else if (serve) {
-    _Viewer._cloneAndServe();
+    } 
+  } else if (compile || serve) {
+    _createViewer(serve);
   }
   return result;
 }
 
+void _createViewer(bool serve) {
+  _Viewer._clone();
+  _Viewer._compile();
+  if (serve) {
+     _Viewer._runServer();
+   }
+} 
+
 /// 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.
   // We have two different places to look, depending if we're in a development
   // repo or in a built SDK, either sdk or dart-sdk respectively
   var root = _Generator._rootDirectory;
@@ skipping 87 matching lines @@
 
   /// This is set from the command line arguments flag --include-private
   static bool _includePrivate = false;
 
   /// Library names to explicitly exclude.
   ///
   ///   Set from the command line option
   /// --exclude-lib.
   static List<String> _excluded;
 
+  /// The path of the pub script.
+  static String _pubScript;
+
+  /// The path of Dart binary.
+  static String _dartBinary;
+
   /// Logger for printing out progress of documentation generation.
   static Logger logger = new Logger('Docgen');
 
   /// Docgen constructor initializes the link resolver for markdown parsing.
   /// Also initializes the command line arguments.
   ///
   /// [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.
   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, String startPage}) {
+       bool includeDependentPackages: false, String startPage,
+       String dartBinary, String pubScript}) {
     _excluded = excludeLibraries;
     _includePrivate = includePrivate;
+    _pubScript = pubScript;
+    _dartBinary = dartBinary;
+
     logger.onRecord.listen((record) => print(record.message));
 
     _ensureOutputDirectory(out, append);
     var updatedPackageRoot = _obtainPackageRoot(packageRoot, parseSdk, files);
 
     var requestedLibraries = _findLibrariesToDocument(files,
         includeDependentPackages);
 
     var allLibraries = []..addAll(requestedLibraries);
     if (includeSdk) {
@@ skipping 307 matching lines @@
       }
     });
     return libraries;
   }
 
   /// All of the directories for our dependent packages
   /// If this is not a package, return an empty list.
   static List<String> _allDependentPackageDirs(String packageDirectory) {
     var packageName = Library.packageNameFor(packageDirectory);
     if (packageName == '') return [];
-    var dependentsJson = Process.runSync('pub', ['list-package-dirs'],
+    var dependentsJson = Process.runSync(_pubScript, ['list-package-dirs'],
         workingDirectory: packageDirectory, runInShell: true);
     if (dependentsJson.exitCode != 0) {
       print(dependentsJson.stderr);
      }
     var dependents = JSON.decode(dependentsJson.stdout)['packages'];
     return dependents.values.toList();
   }
 
   /// For all the libraries, return a list of the libraries that are part of
   /// the SDK.
@@ skipping 23 matching lines @@
   }
 }
 
 /// Convenience methods wrapped up in a class to pull down the docgen viewer for
 /// a viewable website, and start up a server for viewing.
 class _Viewer {
   static String _dartdocViewerString = path.join(Directory.current.path,
       'dartdoc-viewer');
   static Directory _dartdocViewerDir = new Directory(_dartdocViewerString);
   static Directory _topLevelTempDir;
+  static Directory _webDocsDir;
   static bool movedViewerCode = false;
 
   /// If our dartdoc-viewer code is already checked out, move it to a temporary
   /// directory outside of the package directory, so we don't try to process it
   /// for documentation.
   static void ensureMovedViewerCode() {
     // TODO(efortuna): This will need to be modified to run on anyone's package
     // outside of the checkout!
     if (_dartdocViewerDir.existsSync()) {
       _topLevelTempDir = new Directory(
           _Generator._rootDirectory).createTempSync();
       _dartdocViewerDir.renameSync(_topLevelTempDir.path);
     }
   }
 
   /// Move the dartdoc-viewer code back into place for "webpage deployment."
   static void addBackViewerCode() {
     if (movedViewerCode) _dartdocViewerDir.renameSync(_dartdocViewerString);
   }
 
   /// Serve up our generated documentation for viewing in a browser.
-  static void _cloneAndServe() {
+  static void _clone() {
     // If the viewer code is already there, then don't clone again.
     if (_dartdocViewerDir.existsSync()) {
       _moveDirectoryAndServe();
     }
     else {
       var processResult = Process.runSync('git', ['clone', '-b', 'master',
           'git://github.com/dart-lang/dartdoc-viewer.git'],
           runInShell: true);
 
       if (processResult.exitCode == 0) {
-        _moveDirectoryAndServe();
+        /// Move the generated json/yaml docs directory to the dartdoc-viewer
+        /// directory, to run as a webpage.
+        var processResult = Process.runSync(_Generator._pubScript,
+            ['upgrade'], runInShell: true, 
+            workingDirectory: path.join(_dartdocViewerDir.path, 'client'));
+        print('process output: ${processResult.stdout}');
+        print('process stderr: ${processResult.stderr}');
+
+        var dir = new Directory(_Generator._outputDirectory == null? 'docs' :
+            _Generator._outputDirectory);
+        _webDocsDir = new Directory(path.join(_dartdocViewerDir.path, 'client',
+            'web', 'docs'));
+        if (dir.existsSync()) {
+          // Move the docs folder to dartdoc-viewer/client/web/docs
+          dir.renameSync(_webDocsDir.path);
+        }
       } else {
         print('Error cloning git repository:');
         print('process output: ${processResult.stdout}');
         print('process stderr: ${processResult.stderr}');
       }
     }
   }
 
-  /// Move the generated json/yaml docs directory to the dartdoc-viewer
-  /// directory, to run as a webpage.
-  static void _moveDirectoryAndServe() {
-    var processResult = Process.runSync('pub', ['update'], runInShell: true,
-        workingDirectory: path.join(_dartdocViewerDir.path, 'client'));
-    print('process output: ${processResult.stdout}');
-    print('process stderr: ${processResult.stderr}');
-
-    var dir = new Directory(_Generator._outputDirectory == null? 'docs' :
-        _Generator._outputDirectory);
-    var webDocsDir = new Directory(path.join(_dartdocViewerDir.path, 'client',
-        'web', 'docs'));
-    if (dir.existsSync()) {
-      // Move the docs folder to dartdoc-viewer/client/web/docs
-      dir.renameSync(webDocsDir.path);
-    }
-
-    if (webDocsDir.existsSync()) {
+  static void _compile() {
+    if (_webDocsDir.existsSync()) {
       // Compile the code to JavaScript so we can run on any browser.
       print('Compile app to JavaScript for viewing.');
-      var processResult = Process.runSync('dart', ['deploy.dart'],
-          workingDirectory : path.join(_dartdocViewerDir.path, 'client'),
-          runInShell: true);
+      var processResult = Process.runSync(_Generator._dartBinary,
+          ['deploy.dart'], workingDirectory : path.join(_dartdocViewerDir.path,
+          'client'), runInShell: true);
       print('process output: ${processResult.stdout}');
       print('process stderr: ${processResult.stderr}');
-      _runServer();
+      var outputDir = path.join(_dartdocViewerDir.path, 'client', 'out', 'web');
+      print('Docs are available at $outputDir');
     }
   }
 
   /// A simple HTTP server. Implemented here because this is part of the SDK,
   /// so it shouldn't have any external dependencies.
   static void _runServer() {
     // Launch a server to serve out of the directory dartdoc-viewer/client/web.
     HttpServer.bind('localhost', 8080).then((HttpServer httpServer) {
       print('Server launched. Navigate your browser to: '
           'http://localhost:${httpServer.port}');
@@ skipping 1455 matching lines @@
         .map((e) => originalMirror.getField(e.simpleName).reflectee)
         .where((e) => e != null)
         .toList();
   }
 
   Map toMap() => {
     'name': Indexable.getDocgenObject(mirror, owningLibrary).docName,
     'parameters': parameters
   };
 }