Skip to content

Commit 707fe58

Browse files
sethladdsethladd
committed
Docs homepage (flutter#3908)
* 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
1 parent 483922d commit 707fe58

File tree

3 files changed

+67
-22
lines changed

3 files changed

+67
-22
lines changed

‎dev/docs/.gitignore‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,5 +4,5 @@ packages
44
pubspec.lock
55

66
pubspec.yaml
7-
doc/api/
7+
doc/
88
lib/

‎dev/tools/dartdoc.dart‎

Lines changed: 60 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -8,9 +8,16 @@ import 'dart:io';
88

99
import 'package:path/path.dart' as path;
1010

11+
const String kDocRoot = 'dev/docs/doc';
12+
1113
/// This script expects to run with the cwd as the root of the flutter repo. It
1214
/// will generate documentation for the packages in `//packages/` and write the
1315
/// documentation to `//dev/docs/doc/api/`.
16+
///
17+
/// This script also updates the index.html file so that it can be placed
18+
/// at the root of docs.flutter.io. We are keeping the files inside of
19+
/// docs.flutter.io/flutter for now, so we need to manipulate paths
20+
/// a bit. See https://github.com/flutter/flutter/issues/3900 for more info.
1421
Future<Null> main(List<String> args) async {
1522
// If we're run from the `tools` dir, set the cwd to the repo root.
1623
if (path.basename(Directory.current.path) == 'tools')
@@ -21,7 +28,7 @@ Future<Null> main(List<String> args) async {
2128
name: Flutter
2229
dependencies:
2330
''');
24-
for (String package in _findPackageNames()) {
31+
for (String package in findPackageNames()) {
2532
buf.writeln(' $package:');
2633
buf.writeln(' path: ../../packages/$package');
2734
}
@@ -32,15 +39,15 @@ dependencies:
3239
libDir.createSync();
3340

3441
StringBuffer contents = new StringBuffer('library temp_doc;\n\n');
35-
for (String libraryRef in _libraryRefs()) {
42+
for (String libraryRef in libraryRefs()) {
3643
contents.writeln('import \'package:$libraryRef\';');
3744
}
3845
new File('dev/docs/lib/temp_doc.dart').writeAsStringSync(contents.toString());
3946

4047
// Run pub.
4148
Process process = await Process.start('pub', <String>['get'], workingDirectory: 'dev/docs');
42-
_print(process.stdout);
43-
_print(process.stderr);
49+
printStream(process.stdout);
50+
printStream(process.stderr);
4451
int code = await process.exitCode;
4552
if (code != 0)
4653
exit(code);
@@ -56,24 +63,61 @@ dependencies:
5663
'--use-categories'
5764
];
5865

59-
for (String libraryRef in _libraryRefs()) {
66+
for (String libraryRef in libraryRefs()) {
6067
String name = path.basename(libraryRef);
6168
args.add('--include-external');
6269
args.add(name.substring(0, name.length - 5));
6370
}
6471

65-
_findSkyServicesLibraryNames().forEach((String libName) {
72+
findSkyServicesLibraryNames().forEach((String libName) {
6673
args.add('--include-external');
6774
args.add(libName);
6875
});
6976

7077
process = await Process.start('pub', args, workingDirectory: 'dev/docs');
71-
_print(process.stdout);
72-
_print(process.stderr);
73-
exit(await process.exitCode);
78+
printStream(process.stdout);
79+
printStream(process.stderr);
80+
int exitCode = await process.exitCode;
81+
82+
if (exitCode != 0)
83+
exit(exitCode);
84+
85+
createIndexAndCleanup();
86+
}
87+
88+
/// Creates a custom index.html because we try to maintain old
89+
/// paths. Cleanup unused index.html files no longer needed.
90+
void createIndexAndCleanup() {
91+
print('\nCreating a custom index.html in $kDocRoot/index.html');
92+
renameApiDir();
93+
copyIndexToRootOfDocs();
94+
addHtmlBaseToIndex();
95+
putRedirectInOldIndexLocation();
96+
print('\nDocs ready to go!');
97+
}
98+
99+
void renameApiDir() {
100+
new Directory('$kDocRoot/api').renameSync('$kDocRoot/flutter');
101+
}
102+
103+
File copyIndexToRootOfDocs() {
104+
return new File('$kDocRoot/flutter/index.html').copySync('$kDocRoot/index.html');
105+
}
106+
107+
void addHtmlBaseToIndex() {
108+
File indexFile = new File('$kDocRoot/index.html');
109+
String indexContents = indexFile.readAsStringSync();
110+
indexContents = indexContents.replaceFirst('</title>\n',
111+
'</title>\n <base href="./flutter/">\n');
112+
indexFile.writeAsStringSync(indexContents);
113+
}
114+
115+
void putRedirectInOldIndexLocation() {
116+
String metaTag = '<meta http-equiv="refresh" content="0;URL=../index.html">';
117+
new File('$kDocRoot/flutter/index.html').writeAsStringSync(metaTag);
74118
}
75119

76-
List<String> _findSkyServicesLibraryNames() {
120+
List<String> findSkyServicesLibraryNames() {
77121
Directory skyServicesLocation = new Directory('bin/cache/pkg/sky_services/lib');
78122
if (!skyServicesLocation.existsSync()) {
79123
throw 'Did not find sky_services package location in ${skyServicesLocation.path}.';
@@ -88,11 +132,11 @@ List<String> _findSkyServicesLibraryNames() {
88132
});
89133
}
90134

91-
List<String> _findPackageNames() {
92-
return _findPackages().map((Directory dir) => path.basename(dir.path)).toList();
135+
List<String> findPackageNames() {
136+
return findPackages().map((Directory dir) => path.basename(dir.path)).toList();
93137
}
94138

95-
List<Directory> _findPackages() {
139+
List<Directory> findPackages() {
96140
return new Directory('packages')
97141
.listSync()
98142
.where((FileSystemEntity entity) => entity is Directory)
@@ -104,8 +148,8 @@ List<Directory> _findPackages() {
104148
.toList();
105149
}
106150

107-
Iterable<String> _libraryRefs() sync* {
108-
for (Directory dir in _findPackages()) {
151+
Iterable<String> libraryRefs() sync* {
152+
for (Directory dir in findPackages()) {
109153
String dirName = path.basename(dir.path);
110154

111155
for (FileSystemEntity file in new Directory('${dir.path}/lib').listSync()) {
@@ -115,7 +159,7 @@ Iterable<String> _libraryRefs() sync* {
115159
}
116160
}
117161

118-
void _print(Stream<List<int>> stream) {
162+
void printStream(Stream<List<int>> stream) {
119163
stream
120164
.transform(UTF8.decoder)
121165
.transform(const LineSplitter())

‎infra/docs.sh‎

Lines changed: 6 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -6,14 +6,15 @@ pub global activate dartdoc
66

77
# Generate flutter docs into dev/docs/doc/api/.
88
(cd dev/tools; pub get)
9+
10+
# This script generates a unified doc set, and creates
11+
# a custom index.html, placing everything into dev/docs/doc
912
dart dev/tools/dartdoc.dart
1013

11-
cp dev/docs/google2ed1af765c529f57.html dev/docs/doc/api
14+
# Ensure google webmaster tools can verify our site.
15+
cp dev/docs/google2ed1af765c529f57.html dev/docs/doc
1216

1317
# Upload the docs.
1418
if [ "$1" = "--upload" ]; then
15-
# TODO: delete this line when we publish our API docs into the
16-
# root of the bucket
17-
gsutil cp dev/docs/google2ed1af765c529f57.html gs://docs.flutter.io
18-
gsutil -m rsync -d -r dev/docs/doc/api gs://docs.flutter.io/flutter
19+
gsutil -m rsync -d -r dev/docs/doc/ gs://docs.flutter.io/
1920
fi

0 commit comments

Comments
 (0)