Navigation in generated docs.

utils/dartdoc/dartdoc.dart

 // Copyright (c) 2011, 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('../../frog/lang.dart');
 #import('../../frog/file_system.dart');
 #import('../../frog/file_system_node.dart');
 #import('../markdown/lib.dart', prefix: 'md');
 
 #source('classify.dart');
+#source('files.dart');
+#source('utils.dart');
 
 /** Path to corePath library. */
 final corePath = 'lib';
 
 /** Path to generate html files into. */
 final outdir = 'docs';
 
 /** Set to `true` to include the source code in the generated docs. */
-bool includeSource = true;
+bool includeSource = false;
 
 /** Special comment position used to store the library-level doc comment. */
 final _libraryDoc = -1;
 
-/** The path to the file currently being written to, relative to [outdir]. */
-String _filePath;
-
-/** The file currently being written to. */
-StringBuffer _file;
-
 /** The library that we're currently generating docs for. */
 Library _currentLibrary;
 
 /** The type that we're currently generating docs for. */
 Type _currentType;
 
 /** The member that we're currently generating docs for. */
 Member _currentMember;
 
 /**
  * The cached lookup-table to associate doc comments with spans. The outer map
  * is from filenames to doc comments in that file. The inner map maps from the
  * token positions to doc comments. Each position is the starting offset of the
  * next non-comment token *following* the doc comment. For example, the position
  * for this comment would be the position of the "Map" token below.
  */
 Map<String, Map<int, String>> _comments;
 
 int _totalLibraries = 0;
 int _totalTypes = 0;
 int _totalMembers = 0;
 
-FileSystem files;
-
 /**
  * Run this from the `utils/dartdoc` directory.
  */
 void main() {
   // The entrypoint of the library to generate docs for.
   final libPath = process.argv[2];
 
   // Parse the dartdoc options.
   for (int i = 3; i < process.argv.length; i++) {
     final arg = process.argv[i];
@@ skipping 18 matching lines @@
   md.setImplicitLinkResolver(resolveNameReference);
 
   final elapsed = time(() {
     initializeDartDoc();
 
     initializeWorld(files);
 
     world.processDartScript(libPath);
     world.resolveAll();
 
-    // Clean the output directory.
-    if (files.fileExists(outdir)) {
-      files.removeDirectory(outdir, recursive: true);
-    }
-    files.createDirectory(outdir, recursive: true);
-
-    // Copy over the static files.
-    for (final file in ['interact.js', 'styles.css']) {
-      copyStatic(file);
-    }
-
     // Generate the docs.
     for (final library in world.libraries.getValues()) {
       docLibrary(library);
     }
 
     docIndex(world.libraries.getValues());
   });
 
   print('Documented $_totalLibraries libraries, $_totalTypes types, and ' +
         '$_totalMembers members in ${elapsed}msec.');
 }
 
 void initializeDartDoc() {
   _comments = <String, Map<int, String>>{};
 }
 
-/** Copies the static file at 'static/file' to the output directory. */
-copyStatic(String file) {
-  var contents = files.readAll(joinPaths('static', file));
-  files.writeString(joinPaths(outdir, file), contents);
-}
-
-num time(callback()) {
-  // Unlike world.withTiming, returns the elapsed time.
-  final watch = new Stopwatch();
-  watch.start();
-  callback();
-  watch.stop();
-  return watch.elapsedInMs();
-}
-
-startFile(String path) {
-  _filePath = path;
-  _file = new StringBuffer();
-}
-
-write(String s) {
-  _file.add(s);
-}
-
-writeln(String s) {
-  write(s);
-  write('\n');
-}
-
-endFile() {
-  String outPath = '$outdir/$_filePath';
-  files.createDirectory(dirname(outPath), recursive: true);
-
-  world.files.writeString(outPath, _file.toString());
-  _filePath = null;
-  _file = null;
-}
-
-/** Turns a library name into something that's safe to use as a file name. */
-sanitize(String name) => name.replaceAll(':', '_').replaceAll('/', '_');
-
 docIndex(List<Library> libraries) {
   startFile('index.html');
   // TODO(rnystrom): Need to figure out what this should look like.
   writeln(
       '''
       <html><head>
       <title>Index</title>
       <link rel="stylesheet" type="text/css" href="styles.css" />
       </head>
       <body>
@@ skipping 14 matching lines @@
   writeln(
       '''
       </ul>
       </div>
       </body></html>
       ''');
 
   endFile();
 }
 
-/** Returns the number of times [search] occurs in [text]. */
-int countOccurrences(String text, String search) {
-  int start = 0;
-  int count = 0;
-
-  while (true) {
-    start = text.indexOf(search, start);
-    if (start == -1) break;
-    count++;
-    // Offsetting by needle length means overlapping needles are not counted.
-    start += search.length;
-  }
-
-  return count;
-}
-
-/** Repeats [text] [count] times, separated by [separator] if given. */
-String repeat(String text, int count, [String separator]) {
-  // TODO(rnystrom): Should be in corelib.
-  final buffer = new StringBuffer();
-  for (int i = 0; i < count; i++) {
-    buffer.add(text);
-    if ((i < count - 1) && (separator !== null)) buffer.add(separator);
-  }
-
-  return buffer.toString();
-}
-
-/**
- * Converts [absolute] which is understood to be a full path from the root of
- * the generated docs to one relative to the current file.
- */
-String relativePath(String absolute) {
-  // TODO(rnystrom): Walks all the way up to root each time. Shouldn't do this
-  // if the paths overlap.
-  return repeat('../', countOccurrences(_filePath, '/')) + absolute;
-}
-
-/**
- * Creates a hyperlink. Handles turning the [href] into an appropriate relative
- * path from the current file.
- */
-String a(String href, String contents, [String class]) {
-  final css = class == null ? '' : ' class="$class"';
-  return '<a href="${relativePath(href)}"$css>$contents</a>';
-}
-
 writeHeader(String title) {
   writeln(
       '''
       <!DOCTYPE html>
       <html>
       <head>
       <meta charset="utf-8">
       <title>$title</title>
       <link rel="stylesheet" type="text/css"
           href="${relativePath('styles.css')}" />
       <link href="http://fonts.googleapis.com/css?family=Open+Sans:400,600,700,800" rel="stylesheet" type="text/css">
       <script src="${relativePath('interact.js')}"></script>
       </head>
       <body>
-      <div class="content">
+      <div class="page">
       ''');
+  docNavigation();
+  writeln('<div class="content">');
 }
 
 writeFooter() {
   writeln(
       '''
       </div>
+      <div class="footer"</div>
       </body></html>
       ''');
 }
 
+docNavigation() {
+  writeln(
+      '''
+      <div class="nav">
+      <h1>Libraries</h1>
+      ''');
+
+  for (final library in orderValuesByKeys(world.libraries)) {
+    write('<h2><div class="icon-library"></div> ');
+
+    if ((_currentLibrary == library) && (_currentType == null)) {
+      write('<strong>${library.name}</strong>');
+    } else {
+      write('${a(libraryUrl(library), library.name)}');
+    }
+    write('</h2>');
+
+    final types = orderValuesByKeys(library.types);
+    if (types.length > 0) {
+      writeln('<ul>');
+      for (final type in types) {
+        if (type.isTop) continue;
+        if (type.name.startsWith('_')) continue;
+
+        var icon = type.isClass ? 'icon-class' : 'icon-interface';
+        write('<li><div class="$icon"></div> ');
+
+        if (_currentType == type) {
+          write('<strong>${type.name}</strong>');
+        } else {
+          write('${a(typeUrl(type), type.name)}');
+        }
+
+        writeln('</li>');
+      }
+
+      writeln('</ul>');
+    }
+  }
+
+  writeln('</div>');
+}
+
 docLibrary(Library library) {
   _totalLibraries++;
   _currentLibrary = library;
+  _currentType = null;
 
   startFile(libraryUrl(library));
   writeHeader(library.name);
   writeln('<h1>Library <strong>${library.name}</strong></h1>');
 
   // Look for a comment for the entire library.
   final comment = findCommentInFile(library.baseSource, _libraryDoc);
   if (comment != null) {
     final html = md.markdownToHtml(comment);
     writeln('<div class="doc">$html</div>');
   }
 
   // Document the top-level members.
   docMembers(library.topType);
 
   // TODO(rnystrom): Link to types.
   writeln('<h3>Types</h3>');
 
   for (final type in orderValuesByKeys(library.types)) {
     if (type.isTop) continue;
+    if (type.name.startsWith('_')) continue;
     writeln(
         '''
         <div class="type">
         <h4>
           ${type.isClass ? "class" : "interface"}
           ${a(typeUrl(type), "<strong>${typeName(type)}</strong>")}
         </h4>
         </div>
         ''');
   }
@@ skipping 149 matching lines @@
   if (method.isConstructor) {
     write(method.isConst ? 'const ' : 'new ');
   }
 
   if (constructorName == null) {
     write(annotation(type, method.returnType));
   }
 
   // Translate specially-named methods: getters, setters, operators.
   var name = method.name;
-  if (name.startsWith('get\$')) {
+  if (name.startsWith('get:')) {
     // Getter.
     name = 'get ${name.substring(4)}';
-  } else if (name.startsWith('set\$')) {
+  } else if (name.startsWith('set:')) {
     // Setter.
     name = 'set ${name.substring(4)}';
   } else {
     // See if it's an operator.
     name = TokenKind.rawOperatorFromMethod(name);
     if (name == null) {
       name = method.name;
     } else {
       name = 'operator $name';
     }
@@ skipping 49 matching lines @@
       <strong>${field.name}</strong> <a class="anchor-link"
           href="#${memberAnchor(field)}"
           title="Permalink to ${typeName(type)}.${field.name}">#</a>
       </h4>
       ''');
 
   docCode(field.span, showCode: true);
   writeln('</div>');
 }
 
+/**
+ * Creates a hyperlink. Handles turning the [href] into an appropriate relative
+ * path from the current file.
+ */
+String a(String href, String contents, [String class]) {
+  final css = class == null ? '' : ' class="$class"';
+  return '<a href="${relativePath(href)}"$css>$contents</a>';
+}
+
 /** Generates a human-friendly string representation for a type. */
 typeName(Type type) {
   // See if it's a generic type.
   if (type.isGeneric) {
     final typeParams = type.genericType.typeParameters;
     final params = Strings.join(map(typeParams, (p) => p.name), ', ');
     return '${type.name}&lt;$params&gt;';
   }
 
   // See if it's an instantiation of a generic type.
   final typeArgs = type.typeArgsInOrder;
   if (typeArgs != null) {
     final args = Strings.join(map(typeArgs, typeName), ', ');
     return '${type.genericType.name}&lt;$args&gt;';
   }
 
   // Regular type.
   return type.name;
 }
 
-/** Gets the URL to the documentation for [library]. */
-libraryUrl(Library library) {
-  return '${sanitize(library.name)}.html';
-}
-
-/** Gets the URL for the documentation for [type]. */
-typeUrl(Type type) {
-  // Always get the generic type to strip off any type parameters or arguments.
-  // If the type isn't generic, genericType returns `this`, so it works for
-  // non-generic types too.
-  return '${sanitize(type.library.name)}/${type.genericType.name}.html';
-}
-
-/** Gets the URL for the documentation for [member]. */
-memberUrl(Member member) {
-  return '${typeUrl(member.declaringType)}#${member.name}';
-}
-
-/** Gets the anchor id for the document for [member]. */
-memberAnchor(Member member) => '${member.name}';
-
 /** Writes a linked cross reference to [type]. */
 typeReference(Type type) {
   // TODO(rnystrom): Do we need to handle ParameterTypes here like
   // annotation() does?
   return a(typeUrl(type), typeName(type), class: 'crossref');
 }
 
 /**
  * Creates a linked string for an optional type annotation. Returns an empty
  * string if the type is Dynamic.
@@ skipping 177 matching lines @@
   // Syntax highlight.
   return classifySource(new SourceFile('', code));
 }
 
 // TODO(rnystrom): Move into SourceSpan?
 int getSpanColumn(SourceSpan span) {
   final line = span.file.getLine(span.start);
   return span.file.getColumn(line, span.start);
 }
 
-/** Removes up to [indentation] leading whitespace characters from [text]. */
-unindent(String text, int indentation) {
-  var start;
-  for (start = 0; start < Math.min(indentation, text.length); start++) {
-    // Stop if we hit a non-whitespace character.
-    if (text[start] != ' ') break;
-  }
-
-  return text.substring(start);
-}
-
 /**
  * Pulls the raw text out of a doc comment (i.e. removes the comment
  * characters).
  */
 stripComment(comment) {
   StringBuffer buf = new StringBuffer();
 
   for (final line in comment.split('\n')) {
     line = line.trim();
     if (line.startsWith('/**')) line = line.substring(3, line.length);
     if (line.endsWith('*/')) line = line.substring(0, line.length - 2);
     line = line.trim();
     if (line.startsWith('* ')) {
       line = line.substring(2, line.length);
     } else if (line.startsWith('*')) {
       line = line.substring(1, line.length);
     }
 
     buf.add(line);
     buf.add('\n');
   }
 
   return buf.toString();
 }