pkg/docgen: the big refactor

pkg/docgen/lib/src/viewer.dart

+// Copyright (c) 2014, 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.
+
+/// Convenience methods wrapped up in a class to pull down the docgen viewer for
+/// a viewable website, and start up a server for viewing.
+library docgen.viewer;
+
+import 'dart:io';
+
+import 'package:path/path.dart' as path;
+
+import 'generator.dart' as gen;
+import 'package_helpers.dart' show rootDirectory;
+
+final String _dartdocViewerString =
+    path.join(Directory.current.path, 'dartdoc-viewer');
+
+final Directory _dartdocViewerDir = new Directory(_dartdocViewerString);
+
+Directory _topLevelTempDir;
+Directory _webDocsDir;
+bool _movedViewerCode = false;
+
+void createViewer(bool serve) {
+  _clone();
+  _compile();
+  if (serve) {
+    _runServer();
+  }
+}
+
+/*
+ * dartdoc-viewer currently has the web app code under a 'client' directory
+ *
+ * This is confusing for folks that want to clone and modify the code.
+ * It also includes a number of python files and other content related to
+ * app engine hosting that are not needed.
+ *
+ * This logic exists to support the current model and a (future) updated
+ * dartdoc-viewer repo where the 'client' content exists at the root of the
+ * project and the other content is removed.
+ */
+String get _viewerCodePath {
+  if (_viewerCodePathCache == null) {
+    var pubspecFileName = 'pubspec.yaml';
+
+    var thePath = _dartdocViewerDir.path;
+
+    if (!FileSystemEntity.isFileSync(path.join(thePath, pubspecFileName))) {
+      thePath = path.join(thePath, 'client');
+      if (!FileSystemEntity.isFileSync(path.join(thePath, pubspecFileName))) {
+        throw new StateError('Could not find a pubspec file');
+      }
+    }
+
+    _viewerCodePathCache = thePath;
+  }
+  return _viewerCodePathCache;
+}
+String _viewerCodePathCache;
+
+/// 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.
+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(rootDirectory).createTempSync();
+    _dartdocViewerDir.renameSync(_topLevelTempDir.path);
+  }
+}
+
+/// Move the dartdoc-viewer code back into place for "webpage deployment."
+void addBackViewerCode() {
+  if (_movedViewerCode) _dartdocViewerDir.renameSync(_dartdocViewerString);
+}
+
+/// Serve up our generated documentation for viewing in a browser.
+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',
+        'https://github.com/dart-lang/dartdoc-viewer.git'], runInShell: true);
+
+    if (processResult.exitCode == 0) {
+      /// Move the generated json/yaml docs directory to the dartdoc-viewer
+      /// directory, to run as a webpage.
+      var processResult = Process.runSync(gen.pubScript, ['upgrade'],
+          runInShell: true, workingDirectory: _viewerCodePath);
+      print('process output: ${processResult.stdout}');
+      print('process stderr: ${processResult.stderr}');
+
+      var dir = new Directory(gen.outputDirectory == null ? 'docs' :
+          gen.outputDirectory);
+      _webDocsDir = new Directory(path.join(_viewerCodePath, '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.
+void _moveDirectoryAndServe() {
+  var processResult = Process.runSync(gen.pubScript, ['upgrade'], runInShell:
+      true, workingDirectory: path.join(_dartdocViewerDir.path, 'client'));
+  print('process output: ${processResult.stdout}');
+  print('process stderr: ${processResult.stderr}');
+
+  var dir = new Directory(gen.outputDirectory == null ? 'docs' :
+      gen.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()) {
+    // Compile the code to JavaScript so we can run on any browser.
+    print('Compile app to JavaScript for viewing.');
+    var processResult = Process.runSync(gen.dartBinary, ['deploy.dart'],
+        workingDirectory: path.join(_dartdocViewerDir.path, 'client'),
+        runInShell: true);
+    print('process output: ${processResult.stdout}');
+    print('process stderr: ${processResult.stderr}');
+    _runServer();
+  }
+}
+
+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(gen.dartBinary, ['deploy.dart'],
+        workingDirectory: _viewerCodePath, runInShell: true);
+    print('process output: ${processResult.stdout}');
+    print('process stderr: ${processResult.stderr}');
+    var outputDir = path.join(_viewerCodePath, '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.
+void _runServer() {
+  // Launch a server to serve out of the directory dartdoc-viewer/client/web.
+  HttpServer.bind(InternetAddress.ANY_IP_V6, 8080).then((HttpServer httpServer)
+      {
+    print('Server launched. Navigate your browser to: '
+        'http://localhost:${httpServer.port}');
+    httpServer.listen((HttpRequest request) {
+      var response = request.response;
+      var basePath = path.join(_viewerCodePath, 'out', 'web');
+      var requestPath = path.join(basePath, request.uri.path.substring(1));
+      bool found = true;
+      var file = new File(requestPath);
+      if (file.existsSync()) {
+        // Set the correct header type.
+        if (requestPath.endsWith('.html')) {
+          response.headers.set('Content-Type', 'text/html');
+        } else if (requestPath.endsWith('.js')) {
+          response.headers.set('Content-Type', 'application/javascript');
+        } else if (requestPath.endsWith('.dart')) {
+          response.headers.set('Content-Type', 'application/dart');
+        } else if (requestPath.endsWith('.css')) {
+          response.headers.set('Content-Type', 'text/css');
+        }
+      } else {
+        if (requestPath == basePath) {
+          response.headers.set('Content-Type', 'text/html');
+          file = new File(path.join(basePath, 'index.html'));
+        } else {
+          print('Path not found: $requestPath');
+          found = false;
+          response.statusCode = HttpStatus.NOT_FOUND;
+          response.close();
+        }
+      }
+
+      if (found) {
+        // Serve up file contents.
+        file.openRead().pipe(response).catchError((e) {
+          print('HttpServer: error while closing the response stream $e');
+        });
+      }
+    }, onError: (e) {
+      print('HttpServer: an error occured $e');
+    });
+  });
+}