Update dartdoc to v0.18.1 and fix API readme (#16080)

* Update dartdoc to v0.18.1 and fix API readme, borrowing from docs.flutter.io

dev/bots/docs.sh

@@ -6,6 +6,7 @@ echo "Running docs.sh"
 # If you want to run this script locally, make sure you run it from
 # the root of the flutter repository.
 export FLUTTER_ROOT="$PWD"
+export PATH="$PWD/bin:$PATH"
 
 # This is called from travis_upload.sh on Travis.
 
@@ -21,7 +22,7 @@ if [ -d "$FLUTTER_PUB_CACHE" ]; then
 fi
 
 # Install dartdoc.
-bin/cache/dart-sdk/bin/pub global activate dartdoc 0.17.1+1
+bin/cache/dart-sdk/bin/pub global activate dartdoc 0.18.1
 
 # This script generates a unified doc set, and creates
 # a custom index.html, placing everything into dev/docs/doc.

dev/docs/README.md

@@ -1,4 +1,11 @@
-This directory contains the documentation generator for
+Flutter is Google’s mobile UI framework for crafting high-quality native
-<https://docs.flutter.io/>. Those docs are updated only for the beta
+interfaces on iOS and Android in record time. Flutter works with existing code,
-branch, see <../bots/docs.sh>. You can find docs for the master branch
+is used by developers and organizations around the world, and is free and open
-staged at <https://master-docs-flutter-io.firebaseapp.com/>.
+source.
+
+### Documentation
+
+* **Main site: [flutter.io]()**
+* [Install](https://flutter.io/setup/)
+* [Get started](https://flutter.io/getting-started/)
+* [Contribute](CONTRIBUTING.md)

dev/tools/dartdoc.dart

@@ -131,8 +131,7 @@ Future<Null> main(List<String> arguments) async {
     '--exclude',
   'package:Flutter/temp_doc.dart,package:http/browser_client.dart,package:intl/intl_browser.dart,package:matcher/mirror_matchers.dart,package:quiver/mirrors.dart,package:quiver/io.dart,package:vm_service_client/vm_service_client.dart,package:web_socket_channel/html.dart',
     '--favicon=favicon.ico',
-    '--use-categories',
+    '--package-order', 'flutter,Dart,flutter_test,flutter_driver',
-    '--category-order', 'flutter,Dart Core,flutter_test,flutter_driver',
     '--show-warnings',
     '--auto-include-dependencies',
   ]);
@@ -144,6 +143,9 @@ Future<Null> main(List<String> arguments) async {
     dartdocArgs.add(libraryRef);
   }
 
+  String quote(String arg) => arg.contains(' ') ? "'$arg'" : arg;
+  print('Executing: (cd dev/docs ; $pubExecutable ${dartdocArgs.map(quote).join(' ')})');
+
   process = await Process.start(
     pubExecutable,
     dartdocArgs,
@@ -208,32 +210,16 @@ void createFooter(String footerPath) {
 }
 
 void sanityCheckDocs() {
-  // TODO(jcollins-g): remove old_sdk_canaries for dartdoc >= 0.10.0
+  final List<String> canaries = <String>[
-  final List<String> oldSdkCanaries = <String>[
-    '$kDocRoot/api/dart.io/File-class.html',
-    '$kDocRoot/api/dart.ui/Canvas-class.html',
-    '$kDocRoot/api/dart.ui/Canvas/drawRect.html',
-  ];
-  final List<String> newSdkCanaries = <String>[
     '$kDocRoot/api/dart-io/File-class.html',
     '$kDocRoot/api/dart-ui/Canvas-class.html',
     '$kDocRoot/api/dart-ui/Canvas/drawRect.html',
-  ];
+    '$kDocRoot/api/flutter_driver/FlutterDriver/FlutterDriver.connectedTo.html',
-  final List<String> canaries = <String>[
     '$kDocRoot/api/flutter_test/WidgetTester/pumpWidget.html',
     '$kDocRoot/api/material/Material-class.html',
     '$kDocRoot/api/material/Tooltip-class.html',
     '$kDocRoot/api/widgets/Widget-class.html',
   ];
-  bool oldMissing = false;
-  for (String canary in oldSdkCanaries) {
-    if (!new File(canary).existsSync()) {
-      oldMissing = true;
-      break;
-    }
-  }
-  if (oldMissing)
-    canaries.addAll(newSdkCanaries);
   for (String canary in canaries) {
     if (!new File(canary).existsSync())
       throw new Exception('Missing "$canary", which probably means the documentation failed to build correctly.');
@@ -248,6 +234,7 @@ void createIndexAndCleanup() {
   renameApiDir();
   copyIndexToRootOfDocs();
   addHtmlBaseToIndex();
+  changePackageToSdkInTitlebar();
   putRedirectInOldIndexLocation();
   print('\nDocs ready to go!');
 }
@@ -268,6 +255,17 @@ void copyIndexToRootOfDocs() {
   new File('$kDocRoot/flutter/index.html').copySync('$kDocRoot/index.html');
 }
 
+void changePackageToSdkInTitlebar() {
+  final File indexFile = new File('$kDocRoot/index.html');
+  String indexContents = indexFile.readAsStringSync();
+  indexContents = indexContents.replaceFirst(
+    '<li><a href="https://flutter.io">Flutter package</a></li>',
+    '<li><a href="https://flutter.io">Flutter SDK</a></li>',
+  );
+
+  indexFile.writeAsStringSync(indexContents);
+}
+
 void addHtmlBaseToIndex() {
   final File indexFile = new File('$kDocRoot/index.html');
   String indexContents = indexFile.readAsStringSync();