add a dev/dartdoc.dart script to generate docs for the packages/ packages

* add a dev/dartdoc.dart script to generate docs for the packages/ packages

* remove description

* rename readme

* change to using --include-external

* move docs to dev/docs

dev/dartdoc.dart

+#!/usr/bin/env dart
+
+// Copyright 2016 The Chromium Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+import 'dart:async';
+import 'dart:convert';
+import 'dart:io';
+
+/// This script expects to run with the cwd as the root of the flutter repo. It
+/// will generate documentation for the packages in `packages/`, and leave the
+/// documentation in `dev/docs/doc/api/`.
+main(List<String> args) async {
+  // Create the pubspec.yaml file.
+  StringBuffer buf = new StringBuffer('''
+name: Flutter
+dependencies:
+''');
+  for (String package in _findPackageNames()) {
+    buf.writeln('  $package:');
+    buf.writeln('    path: ../../packages/$package');
+  }
+  new File('dev/docs/pubspec.yaml').writeAsStringSync(buf.toString());
+
+  // Create the library file.
+  Directory libDir = new Directory('dev/docs/lib');
+  libDir.createSync();
+
+  StringBuffer contents = new StringBuffer('library temp_doc;\n\n');
+  for (String libraryRef in _libraryRefs()) {
+    contents.writeln('import \'package:$libraryRef\';');
+  }
+  new File('dev/docs/lib/temp_doc.dart').writeAsStringSync(contents.toString());
+
+  // Run pub.
+  Process process = await Process.start('pub', <String>['get'], workingDirectory: 'dev/docs');
+  _print(process.stdout);
+  _print(process.stderr);
+  int code = await process.exitCode;
+  if (code != 0)
+    exit(code);
+
+  // Generate the documentation; we require dartdoc >= 0.9.3+1.
+  List<String> args = <String>[
+    'global', 'run', 'dartdoc',
+    '--header', 'styles.html',
+    '--header', 'analytics.html',
+    '--dart-sdk', '../../bin/cache/dart-sdk',
+    '--exclude', 'temp_doc'
+  ];
+  for (String libraryRef in _libraryRefs()) {
+    String name = _entityName(libraryRef);
+
+    args.add('--include-external');
+    args.add(name.substring(0, name.length - 5));
+  }
+
+  process = await Process.start('pub', args, workingDirectory: 'dev/docs');
+  _print(process.stdout);
+  _print(process.stderr);
+  exit(await process.exitCode);
+}
+
+List<String> _findPackageNames() {
+  return _findPackages().map((Directory dir) => _entityName(dir.path)).toList();
+}
+
+List<Directory> _findPackages() {
+  return new Directory('packages')
+    .listSync()
+    .where((FileSystemEntity entity) => entity is Directory)
+    .where((Directory dir) {
+      File pubspec = new File('${dir.path}/pubspec.yaml');
+      bool nodoc = pubspec.readAsStringSync().contains('nodoc: true');
+      return !nodoc;
+    })
+    .toList();
+
+}
+
+List<String> _libraryRefs() sync* {
+  for (Directory dir in _findPackages()) {
+    String dirName = _entityName(dir.path);
+
+    for (FileSystemEntity file in new Directory('${dir.path}/lib').listSync()) {
+      if (file is File && file.path.endsWith('.dart'))
+        yield '$dirName/${_entityName(file.path)}';
+    }
+  }
+}
+
+String _entityName(String path) {
+  return path.indexOf('/') == -1 ? path : path.substring(path.lastIndexOf('/') + 1);
+}
+
+void _print(Stream<List<int>> stream) {
+  stream
+    .transform(UTF8.decoder)
+    .transform(const LineSplitter())
+    .listen(print);
+}

dev/docs/.analysis_options

+analyzer:
+  exclude:
+    - 'lib/**'

dev/docs/.gitignore

+.pub/
+packages
+.packages
+pubspec.lock
+
+pubspec.yaml
+api/
+lib/

dev/docs/README.md

+Flutter is a new way to build high-performance, cross-platform mobile apps.
+Flutter is optimized for today's, and tomorrow's, mobile devices. We are focused
+on low-latency input and high frame rates on Android and iOS.
+
+See the [getting started guide](https://flutter.io/getting-started/) for
+information about using Flutter.

dev/docs/analytics.html

+<script>
+  (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
+  (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
+  m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
+  })(window,document,'script','//www.google-analytics.com/analytics.js','ga');
+
+  ga('create', 'UA-67589403-2', 'auto');
+  ga('send', 'pageview');
+</script>

dev/docs/styles.html

+<!-- style overrides for dartdoc -->
+<style>
+  header {
+    background-color: #917FFF;
+  }
+
+  body {
+    font-size: 16px;
+    line-height: 1.5;
+    color: #111;
+    background-color: #fdfdfd;
+  }
+
+  h1, h2, h3, h4, h5, h6 {
+    font-weight: 300;
+  }
+
+  h1 {
+    font-size: 42px !important;
+    letter-spacing: -1px;
+    line-height: 1;
+  }
+
+  h2 {
+    font-size: 32px;
+  }
+
+  pre > code {
+    font-size: 14px;
+  }
+</style>
+
+<!-- The following rules are from http://google.github.io/material-design-icons/ -->
+<link href="https://fonts.googleapis.com/icon?family=Material+Icons" rel="stylesheet">
+<style>
+  /* Rules for sizing the icon. */
+  .material-icons.md-18 { font-size: 18px; }
+  .material-icons.md-24 { font-size: 24px; }
+  .material-icons.md-36 { font-size: 36px; }
+  .material-icons.md-48 { font-size: 48px; }
+
+  /* Rules for using icons as black on a light background. */
+  .material-icons.md-dark { color: rgba(0, 0, 0, 0.54); }
+  .material-icons.md-dark.md-inactive { color: rgba(0, 0, 0, 0.26); }
+
+  /* Rules for using icons as white on a dark background. */
+  .material-icons.md-light { color: rgba(255, 255, 255, 1); }
+  .material-icons.md-light.md-inactive { color: rgba(255, 255, 255, 0.3); }
+</style>

dev/profile_startup.dart

@@ -3,9 +3,9 @@
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
-import 'dart:io';
 import 'dart:async';
 import 'dart:convert';
+import 'dart:io';
 
 const int ITERATIONS = 5;
 

doc/_analytics.html

@@ -6,5 +6,4 @@
 
   ga('create', 'UA-67589403-2', 'auto');
   ga('send', 'pageview');
-
 </script>

packages/flutter_markdown/lib/flutter_markdown.dart

@@ -2,6 +2,7 @@
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
+/// A library to render markdown formatted text.
 library flutter_markdown;
 
 export 'src/markdown.dart';

packages/flutter_markdown/lib/flutter_markdown_raw.dart

@@ -2,7 +2,7 @@
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
-library flutter_markdown;
+library flutter_markdown_raw;
 
 export 'src/markdown_raw.dart';
 export 'src/markdown_style_raw.dart';

packages/flutter_tools/pubspec.yaml

@@ -41,3 +41,7 @@ dependencies:
 
 dev_dependencies:
   mockito: ^0.11.0
+
+# Exclude this package from the hosted API docs.
+dartdoc:
+  nodoc: true

packages/flx/pubspec.yaml

@@ -16,3 +16,7 @@ dev_dependencies:
   flutter_tools:
     path: ../flutter_tools
   test: any # constrained by the dependency in flutter_tools
+
+# Exclude this package from the hosted API docs.
+dartdoc:
+  nodoc: true