Docs homepage (flutter#3908)

sethladd · sethladd · commit 707fe582a669 · 2016-05-16T08:28:58.000-07:00
* put an index at root of API docs bucket

* ignore all of dev/docs/doc dir, fix a bug, remove private names from doc gen script

* tweaks from review
diff --git a/dev/docs/.gitignore b/dev/docs/.gitignore
@@ -4,5 +4,5 @@ packages
 pubspec.lock
 
 pubspec.yaml
-doc/api/
+doc/
 lib/
diff --git a/dev/tools/dartdoc.dart b/dev/tools/dartdoc.dart
@@ -8,9 +8,16 @@ import 'dart:io';
 
 import 'package:path/path.dart' as path;
 
+const String kDocRoot = 'dev/docs/doc';
+
 /// 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 write the
 /// documentation to `//dev/docs/doc/api/`.
+/// 
+/// This script also updates the index.html file so that it can be placed
+/// at the root of docs.flutter.io. We are keeping the files inside of
+/// docs.flutter.io/flutter for now, so we need to manipulate paths
+/// a bit. See https://github.com/flutter/flutter/issues/3900 for more info.
 Future<Null> main(List<String> args) async {
   // If we're run from the `tools` dir, set the cwd to the repo root.
   if (path.basename(Directory.current.path) == 'tools')
@@ -21,7 +28,7 @@ Future<Null> main(List<String> args) async {
 name: Flutter
 dependencies:
 ''');
-  for (String package in _findPackageNames()) {
+  for (String package in findPackageNames()) {
     buf.writeln('  $package:');
     buf.writeln('    path: ../../packages/$package');
   }
@@ -32,15 +39,15 @@ dependencies:
   libDir.createSync();
 
   StringBuffer contents = new StringBuffer('library temp_doc;\n\n');
-  for (String libraryRef in _libraryRefs()) {
+  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);
+  printStream(process.stdout);
+  printStream(process.stderr);
   int code = await process.exitCode;
   if (code != 0)
     exit(code);
@@ -56,24 +63,61 @@ dependencies:
     '--use-categories'
   ];
 
-  for (String libraryRef in _libraryRefs()) {
+  for (String libraryRef in libraryRefs()) {
     String name = path.basename(libraryRef);
     args.add('--include-external');
     args.add(name.substring(0, name.length - 5));
   }
 
-  _findSkyServicesLibraryNames().forEach((String libName) {
+  findSkyServicesLibraryNames().forEach((String libName) {
     args.add('--include-external');
     args.add(libName);
   });
 
   process = await Process.start('pub', args, workingDirectory: 'dev/docs');
-  _print(process.stdout);
-  _print(process.stderr);
-  exit(await process.exitCode);
+  printStream(process.stdout);
+  printStream(process.stderr);
+  int exitCode = await process.exitCode;
+
+  if (exitCode != 0)
+    exit(exitCode);
+
+  createIndexAndCleanup();
+}
+
+/// Creates a custom index.html because we try to maintain old
+/// paths. Cleanup unused index.html files no longer needed.
+void createIndexAndCleanup() {
+  print('\nCreating a custom index.html in $kDocRoot/index.html');
+  renameApiDir();
+  copyIndexToRootOfDocs();
+  addHtmlBaseToIndex();
+  putRedirectInOldIndexLocation();
+  print('\nDocs ready to go!');
+}
+
+void renameApiDir() {
+  new Directory('$kDocRoot/api').renameSync('$kDocRoot/flutter');
+}
+
+File copyIndexToRootOfDocs() {
+  return new File('$kDocRoot/flutter/index.html').copySync('$kDocRoot/index.html');
+}
+
+void addHtmlBaseToIndex() {
+  File indexFile = new File('$kDocRoot/index.html');
+  String indexContents = indexFile.readAsStringSync();
+  indexContents = indexContents.replaceFirst('</title>\n',
+    '</title>\n  <base href="./flutter/">\n');
+  indexFile.writeAsStringSync(indexContents);
+}
+
+void putRedirectInOldIndexLocation() {
+  String metaTag = '<meta http-equiv="refresh" content="0;URL=../index.html">';
+  new File('$kDocRoot/flutter/index.html').writeAsStringSync(metaTag);
 }
 
-List<String> _findSkyServicesLibraryNames() {
+List<String> findSkyServicesLibraryNames() {
   Directory skyServicesLocation = new Directory('bin/cache/pkg/sky_services/lib');
   if (!skyServicesLocation.existsSync()) {
     throw 'Did not find sky_services package location in ${skyServicesLocation.path}.';
@@ -88,11 +132,11 @@ List<String> _findSkyServicesLibraryNames() {
   });
 }
 
-List<String> _findPackageNames() {
-  return _findPackages().map((Directory dir) => path.basename(dir.path)).toList();
+List<String> findPackageNames() {
+  return findPackages().map((Directory dir) => path.basename(dir.path)).toList();
 }
 
-List<Directory> _findPackages() {
+List<Directory> findPackages() {
   return new Directory('packages')
     .listSync()
     .where((FileSystemEntity entity) => entity is Directory)
@@ -104,8 +148,8 @@ List<Directory> _findPackages() {
     .toList();
 }
 
-Iterable<String> _libraryRefs() sync* {
-  for (Directory dir in _findPackages()) {
+Iterable<String> libraryRefs() sync* {
+  for (Directory dir in findPackages()) {
     String dirName = path.basename(dir.path);
 
     for (FileSystemEntity file in new Directory('${dir.path}/lib').listSync()) {
@@ -115,7 +159,7 @@ Iterable<String> _libraryRefs() sync* {
   }
 }
 
-void _print(Stream<List<int>> stream) {
+void printStream(Stream<List<int>> stream) {
   stream
     .transform(UTF8.decoder)
     .transform(const LineSplitter())
diff --git a/infra/docs.sh b/infra/docs.sh
@@ -6,14 +6,15 @@ pub global activate dartdoc
 
 # Generate flutter docs into dev/docs/doc/api/.
 (cd dev/tools; pub get)
+
+# This script generates a unified doc set, and creates
+# a custom index.html, placing everything into dev/docs/doc
 dart dev/tools/dartdoc.dart
 
-cp dev/docs/google2ed1af765c529f57.html dev/docs/doc/api
+# Ensure google webmaster tools can verify our site.
+cp dev/docs/google2ed1af765c529f57.html dev/docs/doc
 
 # Upload the docs.
 if [ "$1" = "--upload" ]; then
-  # TODO: delete this line when we publish our API docs into the
-  # root of the bucket
-  gsutil cp dev/docs/google2ed1af765c529f57.html gs://docs.flutter.io
-  gsutil -m rsync -d -r dev/docs/doc/api gs://docs.flutter.io/flutter
+  gsutil -m rsync -d -r dev/docs/doc/ gs://docs.flutter.io/
 fi
