Move Nathan's HTML scripts over and rename to apidoc.

Review URL: http://codereview.chromium.org//8973004

git-svn-id: https://dart.googlecode.com/svn/branches/bleeding_edge/dart@2494 260f80e4-7a28-3924-810f-c04153c831b5

utils/apidoc/.gitignore

@@ -0,0 +1 @@
+docs/

utils/apidoc/README.txt

@@ -0,0 +1,84 @@
+Dartdoc generates static HTML documentation from Dart code.
+
+To use it, from this directory, run:
+
+    $ dartdoc <path to .dart file>
+
+This will create a "docs" directory with the docs for your libraries.
+
+
+How docs are generated
+----------------------
+
+To make beautiful docs from your library, dartdoc parses it 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.
+
+"Doc comments" can be in one of a few forms:
+
+    /**
+     * JavaDoc style block comments.
+     */
+
+    /** Which can also be single line. */
+
+    /// Triple-slash line comments.
+    /// Which can be multiple lines.
+
+The body of a doc comment will be parsed as markdown which means you can apply
+most of the formatting and structuring you want while still having docs that
+look nice in plain text. For example:
+
+    /// This is a doc comment. This is the first paragraph in the comment. It
+    /// can span multiple lines.
+    ///
+    /// A blank line starts a new paragraph like this one.
+    ///
+    /// *   Unordered lists start with `*` or `-` or `+`.
+    /// *   And can have multiple items.
+    ///     1. You can nest lists.
+    ///     2. Like this numbered one.
+    ///
+    /// ---
+    ///
+    /// Three dashes, underscores, or tildes on a line by themselves create a
+    /// horizontal rule.
+    ///
+    ///     to.get(a.block + of.code) {
+    ///       indent(it, 4.lines);
+    ///       like(this);
+    ///     }
+    ///
+    /// There are a few inline styles you can apply: *emphasis*, **strong**,
+    /// and `inline code`. You can also use underscores for _emphasis_ and
+    /// __strong__.
+    ///
+    /// An H1 header using equals on the next line
+    /// ==========================================
+    ///
+    /// And an H2 in that style using hyphens
+    /// -------------------------------------
+    ///
+    /// # Or an H1 - H6 using leading hashes
+    /// ## H2
+    /// ### H3
+    /// #### H4 you can also have hashes at then end: ###
+    /// ##### H5
+    /// ###### H6
+
+There is also an extension to markdown specific to dartdoc: A name inside
+square brackets that is not a markdown link (i.e. doesn't have square brackets
+or parentheses following it) like:
+
+    Calls [someMethod], passing in [arg].
+
+is understood to be the name of some member or type that's in the scope of the
+member where that comment appears. Dartdoc will automatically figure out what
+the name refers to and generate an approriate link to that member or type.
+
+
+Attribution
+-----------
+
+dartdoc uses the delightful Silk icon set by Mark James.
+http://www.famfamfam.com/lab/icons/silk/

utils/apidoc/apidoc

@@ -0,0 +1,46 @@
+#!/bin/bash
+
+# This generates the reference documentation for the core libraries that come
+# with dartdoc. It is built on top of dartdoc, which is a general-purpose
+# library for generating docs from any Dart code. This library extends that to
+# include additional information and styling specific to our corelib.
+#
+# Usage:
+#
+# $ ./apidoc
+#
+# Pretty simple. :)
+
+# TODO(rnystrom): This script is more or less a copy of the one in dartdoc but
+# tweaked to output stuff to here instead of inside dartdoc/docs. That's pretty
+# gross. Ideally, we'd write the whole thing in Dart an ditch the shell
+# but right now we can't even copy binary files using Dart.
+
+# Run from dartdoc directory to get correct relative paths.
+pushd `dirname "$0"` >>/dev/null
+
+# Generate the client-side .js file from interact.dart if we haven't already or
+# if it's out of date.
+if [ "interact.dart" -nt "static/interact.js" ]
+  then
+  ../../frog/minfrog --libdir=../../frog/lib \
+    --out=../dartdoc/static/interact.js --compile-only interact.dart
+  echo "Compiled interact.dart."
+fi
+
+# Clean the output directory.
+if [ -d "docs" ]; then
+    rm -r docs
+fi
+mkdir docs
+
+# Copy the static files over.
+cp ../dartdoc/static/* docs
+
+# Ditch the first arg so we can pass any extra arguments to dartdoc.
+shift
+
+# Generate the user's docs.
+../../frog/minfrog --libdir=../../frog/lib ../apidoc/apidoc.dart
+
+popd >>/dev/null

utils/apidoc/apidoc.dart

@@ -3,21 +3,15 @@
 // BSD-style license that can be found in the LICENSE file.
 
 /**
- * A script to document the HTML library, including annotations on the mapping
- * to and from the DOM library. To use it, from utils/dartdoc, run:
- *
- *     $ htmldoc
- *
- * This works just like `dartdoc html`, with the additions of the DOM/HTML
- * mapping documentation.
+ * Generates the complete set of corelib reference documentation.
  */
-#library('html_doc');
+#library('apidoc');
 
 #import('html_diff.dart');
-#import('../../../frog/lang.dart');
-#import('../../../frog/file_system_node.dart');
-#import('../../../frog/file_system.dart');
-#import('../../../utils/dartdoc/dartdoc.dart', prefix: 'doc');
+#import('../../frog/lang.dart');
+#import('../../frog/file_system_node.dart');
+#import('../../frog/file_system.dart');
+#import('../dartdoc/dartdoc.dart', prefix: 'doc');
 
 HtmlDiff _diff;
 
@@ -25,17 +19,17 @@ void main() {
   var files = new NodeFileSystem();
   parseOptions('../../frog', [] /* args */, files);
   initializeWorld(files);
-  final htmldoc = new Htmldoc();
+  final apidoc = new Apidoc();
   HtmlDiff.initialize();
 
   _diff = new HtmlDiff();
   _diff.run();
   world.reset();
 
-  htmldoc.document('html');
+  apidoc.document('html');
 }
 
-class Htmldoc extends doc.Dartdoc {
+class Apidoc extends doc.Dartdoc {
   getTypeComment(Type type) {
     return _mergeComments(super.getTypeComment(type), getTypeDoc(type));
   }

utils/apidoc/html_diff.dart

@@ -8,10 +8,10 @@
  */
 #library('html_diff');
 
-#import('../../../frog/lang.dart');
-#import('../../../frog/file_system_node.dart');
-#import('../../../frog/file_system.dart');
-#import('../../../utils/dartdoc/dartdoc.dart');
+#import('../../frog/lang.dart');
+#import('../../frog/file_system_node.dart');
+#import('../../frog/file_system.dart');
+#import('../dartdoc/dartdoc.dart');
 
 void main() {
   var files = new NodeFileSystem();

utils/dartdoc/dartdoc.dart

@@ -5,7 +5,7 @@
 /**
  * To use it, from this directory, run:
  *
- *     $ dartdoc <path to .dart file>
+ *     $ ./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