Allow specifying output directory for dartdoc and apidoc.

lib/dartdoc/dartdoc.dart

 // Copyright (c) 2012, 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.
 
 /**
  * To use it, from this directory, run:
  *
  *     $ ./dartdoc <path to .dart file>
  *
  * This will create a "docs" directory with the docs for your libraries. To
  * create these beautiful docs, dartdoc parses your library and every library
  * it imports (recursively). From each library, it parses all classes and
  * members, finds the associated doc comments and builds crosslinked docs from
  * them.
  */
 #library('dartdoc');
 
 #import('dart:io');
 #import('dart:json');
 #import('../../frog/lang.dart');
 #import('../../frog/file_system.dart');
 #import('../../frog/file_system_vm.dart');
 #import('classify.dart');
 #import('markdown.dart', prefix: 'md');
 
 #source('comment_map.dart');
 #source('utils.dart');
 
-/** Path to generate HTML files into. */
-final _outdir = 'docs';
-
 /**
  * Generates completely static HTML containing everything you need to browse
  * the docs. The only client side behavior is trivial stuff like syntax
  * highlighting code.
  */
 final MODE_STATIC = 0;
 
 /**
  * Generated docs do not include baked HTML navigation. Instead, a single
  * `nav.json` file is created and the appropriate navigation is generated
  * client-side by parsing that and building HTML.
  *
  * This dramatically reduces the generated size of the HTML since a large
  * fraction of each static page is just redundant navigation links.
  *
  * In this mode, the browser will do a XHR for nav.json which means that to
  * preview docs locally, you will need to enable requesting file:// links in
  * your browser or run a little local server like `python -m SimpleHTTPServer`.
  */
 final MODE_LIVE_NAV = 1;
 
 /**
  * Run this from the `lib/dartdoc` directory.
  */
 void main() {
   final args = new Options().arguments;
 
-  // The entrypoint of the library to generate docs for.
-  final entrypoint = args[args.length - 1];
+  // Parse the dartdoc options.
+  var includeSource;
+  var mode;
+  var outputDir;

[nweiz, 2012/03/15 23:45:48]

These should have types declared, since they're not initialized here.

[Bob Nystrom, 2012/03/15 23:58:23]

Done.

 
-  // Parse the dartdoc options.
-  bool includeSource = true;
-  var mode = MODE_LIVE_NAV;
+  for (int i = 0; i < args.length - 1; i++) {
+    final arg = args[i];
 
-  for (int i = 2; i < args.length - 1; i++) {
-    final arg = args[i];
     switch (arg) {
       case '--no-code':
         includeSource = false;
         break;
 
       case '--mode=static':
         mode = MODE_STATIC;
         break;
 
       case '--mode=live-nav':
         mode = MODE_LIVE_NAV;
         break;
 
       default:
-        print('Unknown option: $arg');
+        if (arg.startsWith('--out=')) {
+          outputDir = arg.substring('--out='.length);

[nweiz, 2012/03/15 23:45:48]

Is there a bug filed against Options to support options with arguments?

[Bob Nystrom, 2012/03/15 23:58:23]

No, but I don't really think arg parsing should be built into the core options
class. If it was me, I'd have a separate args library to do that.

[nweiz, 2012/03/16 00:15:49]

What's the Options class for if not arg parsing?

[Bob Nystrom, 2012/03/16 00:22:37]

It's for being able to access them at all. I would like nice arg parsing too,
but I'd like that in a separate lib on top of options so that when a better lib
comes along, I'm not stuck with the old one.

[nweiz, 2012/03/16 18:25:51]

Maybe this is more of an API design issue, but the name "Options" seems to
indicate that it provides some, you know, options handling. Especially since
you're instantiating an object.

Anyway, this is pretty off-topic for this CL.

+        } else {
+          print('Unknown option: $arg');
+          return;
+        }

[mattsh, 2012/03/15 23:52:55]

missing break

[Bob Nystrom, 2012/03/15 23:58:23]

Done.

     }
   }
 
+  // The entrypoint of the library to generate docs for.
+  final entrypoint = args[args.length - 1];
+
   final files = new VMFileSystem();
   // TODO(rnystrom): Note that the following line gets munged by create-sdk to
   // work with the SDK's different file layout. If you change it here, make
   // sure SDK builds still work.
   parseOptions('../../frog', ['', '', '--libdir=../../frog/lib'], files);
   initializeWorld(files);
 
   var dartdoc;
   final elapsed = time(() {
     dartdoc = new Dartdoc();
-    dartdoc.includeSource = includeSource;
-    dartdoc.mode = mode;
+
+    if (includeSource != null) dartdoc.includeSource = includeSource;
+    if (mode != null) dartdoc.mode = mode;
+    if (outputDir != null) dartdoc.outputDir = outputDir;
+
+    cleanOutputDirectory(outputDir);
+
+    // TODO(rnystrom): Use platform-specific path separator.

[nweiz, 2012/03/15 23:45:48]

Won't Windows understand "/", even if it doesn't prefer it?

[Bob Nystrom, 2012/03/15 23:58:23]

Not sure. The Platform class in Dart does have a path separator accessor, so it
seems like we should use it. I just don't want to refactor dartdoc right now to
do that.

[nweiz, 2012/03/16 00:15:49]

If we don't have to use the separator constant for this to work, we shouldn't.
Using "/" is much more readable.

[Bob Nystrom, 2012/03/16 00:22:37]

Works for me. I won't plan to change this until I see an actual bug report that
it doesn't work on Windows.

+    copyFiles('$scriptDir/static', outputDir);
 
     dartdoc.document(entrypoint);
   });
 
   print('Documented ${dartdoc._totalLibraries} libraries, ' +
       '${dartdoc._totalTypes} types, and ' +
       '${dartdoc._totalMembers} members in ${elapsed}msec.');
 }
 
+/**
+ * Gets the full path to the directory containing the entrypoint of the current
+ * script. In other words, if you invoked dartdoc, directly, it will be the
+ * path to the directory containing `dartdoc.dart`. If you're running a script
+ * that imports dartdoc, it will be the path to that script.
+ */
+String get scriptDir() {
+  return dirname(new File(new Options().script).fullPathSync());
+}
+
+/**
+ * Deletes and recreates the output directory at [path] if it exists.
+ */
+void cleanOutputDirectory(String path) {
+  final outputDir = new Directory(path);
+  if (outputDir.existsSync()) {
+    outputDir.deleteRecursivelySync();
+    outputDir.createSync();
+  }
+}
+
+/**
+ * Copies all of the files in the directory [from] to [to]. Does *not*
+ * recursively copy subdirectories.
+ *
+ * Note: runs asynchronously, so you won't see any files copied until after the
+ * event loop has had a chance to pump (i.e. after `main()` has returned).
+ */
+void copyFiles(String from, String to) {
+  final fromDir = new Directory(from);
+  fromDir.onFile = (path) {
+    final name = basename(path);
+    // TODO(rnystrom): Hackish. Ignore 'hidden' files like .DS_Store.
+    if (name.startsWith('.')) return;
+
+    new File(path).readAsBytes((bytes) {
+      final outFile = new File('$to/$name');
+      final stream = outFile.openOutputStream(FileMode.WRITE);
+      stream.write(bytes, copyBuffer: false);
+      stream.close();
+    });
+  };
+  fromDir.list(recursive: false);
+}
+
 class Dartdoc {
   /** Set to `false` to not include the source code in the generated docs. */
   bool includeSource = true;
 
   /**
    * Dartdoc can generate docs in a few different ways based on how dynamic you
    * want the client-side behavior to be. The value for this should be one of
    * the `MODE_` constants.
    */
   int mode = MODE_LIVE_NAV;
 
+  /** Path to generate HTML files into. */
+  String outputDir = 'docs';
+
   /**
    * The title used for the overall generated output. Set this to change it.
    */
   String mainTitle = 'Dart Documentation';
 
   /**
    * The URL that the Dart logo links to. Defaults "index.html", the main
    * page for the generated docs, but can be anything.
    */
   String mainUrl = 'index.html';
@@ skipping 110 matching lines @@
       options.dietParse = oldDietParse;
     }
   }
 
   void startFile(String path) {
     _filePath = path;
     _file = new StringBuffer();
   }
 
   void endFile() {
-    final outPath = '$_outdir/$_filePath';
+    final outPath = '$outputDir/$_filePath';
     final dir = new Directory(dirname(outPath));
     if (!dir.existsSync()) {
       dir.createSync();
     }
 
     world.files.writeString(outPath, _file.toString());
     _filePath = null;
     _file = null;
   }
 
@@ skipping 953 matching lines @@
 
     return new md.Element.text('code', name);
   }
 
   // TODO(rnystrom): Move into SourceSpan?
   int getSpanColumn(SourceSpan span) {
     final line = span.file.getLine(span.start);
     return span.file.getColumn(line, span.start);
   }
 }