diff --git a/dev/bots/docs.sh b/dev/bots/docs.sh index dbc1f4ef9f..eba6776323 100755 --- a/dev/bots/docs.sh +++ b/dev/bots/docs.sh @@ -47,6 +47,7 @@ function create_docset() { echo "Building Flutter docset." rm -rf flutter.docset (dashing build --source ./doc --config ./dashing.json > /tmp/dashing.log 2>&1 || (tail -100 /tmp/dashing.log; false)) && \ + cp ./doc/flutter/static-assets/favicon.png ./flutter.docset/icon.png && \ tar cf flutter.docset.tar.gz --use-compress-program="gzip --best" flutter.docset } @@ -62,7 +63,7 @@ function move_offline_into_place() { if [[ "$CIRRUS_BRANCH" == "stable" ]]; then echo -e "\n ${FLUTTER_VERSION}\n https://docs.flutter.io/offline/flutter.docset.tar.gz\n" > doc/offline/flutter.xml else - echo -e "\n ${FLUTTER_VERSION}\n https://master-docs-flutter-io.firebaseapp.com/offline/flutter.docset.tar.gz\n" > doc/offline/flutter.xml + echo -e "\n ${FLUTTER_VERSION}\n https://master-docs.flutter.io/offline/flutter.docset.tar.gz\n" > doc/offline/flutter.xml fi mv flutter.docset.tar.gz doc/offline/flutter.docset.tar.gz du -sh doc/offline/flutter.docset.tar.gz @@ -123,7 +124,7 @@ cp "$FLUTTER_ROOT/dev/docs/google2ed1af765c529f57.html" "$FLUTTER_ROOT/dev/docs/ if [[ -n "$CIRRUS_CI" && -z "$CIRRUS_PR" ]]; then echo "This is not a pull request; considering whether to upload docs... (branch=$CIRRUS_BRANCH)" if [[ "$CIRRUS_BRANCH" == "master" ]]; then - echo "Updating $CIRRUS_BRANCH docs: https://master-docs-flutter-io.firebaseapp.com/" + echo "Updating $CIRRUS_BRANCH docs: https://master-docs.flutter.io/" # Disable search indexing on the master staging site so searches get only # the stable site. echo -e "User-agent: *\nDisallow: /" > "$FLUTTER_ROOT/dev/docs/doc/robots.txt" diff --git a/dev/docs/lib/opensearch.xml b/dev/docs/lib/opensearch.xml new file mode 100644 index 0000000000..888ab40d3b --- /dev/null +++ b/dev/docs/lib/opensearch.xml @@ -0,0 +1,14 @@ + +Flutter API + +Welcome to the Flutter API reference documentation search. + +Flutter is Google’s mobile UI framework for crafting high-quality native interfaces on iOS and Android in record time. +Flutter works with existing code, is used by developers and organizations around the world, and is free and open source. + +The API reference herein covers all libraries that are exported by the Flutter SDK. + +UTF-8 +/flutter/static-assets/favicon.png + + diff --git a/dev/docs/opensearch.html b/dev/docs/opensearch.html new file mode 100644 index 0000000000..07484691ff --- /dev/null +++ b/dev/docs/opensearch.html @@ -0,0 +1 @@ + diff --git a/dev/tools/dartdoc.dart b/dev/tools/dartdoc.dart index 43bc5dde48..2c259cf39e 100644 --- a/dev/tools/dartdoc.dart +++ b/dev/tools/dartdoc.dart @@ -100,6 +100,7 @@ Future main(List arguments) async { createFooter('$kDocsRoot/lib/footer.html'); copyAssets(); + createSearchMetadata('$kDocsRoot/lib/opensearch.xml', '$kDocsRoot/doc/opensearch.xml'); cleanOutSnippets(); final List dartdocBaseArgs = ['global', 'run']; @@ -134,6 +135,7 @@ Future main(List arguments) async { '--header', 'analytics.html', '--header', 'survey.html', '--header', 'snippets.html', + '--header', 'opensearch.html', '--footer-text', 'lib/footer.html', '--exclude-packages', [ @@ -231,20 +233,25 @@ ArgParser _createArgsParser() { final RegExp gitBranchRegexp = RegExp(r'^## (.*)'); +String getBranchName() { + final ProcessResult gitResult = Process.runSync('git', ['status', '-b', '--porcelain']); + if (gitResult.exitCode != 0) + throw 'git status exit with non-zero exit code: ${gitResult.exitCode}'; + final Match gitBranchMatch = gitBranchRegexp.firstMatch( + gitResult.stdout.trim().split('\n').first); + return gitBranchMatch == null ? '' : gitBranchMatch.group(1).split('...').first; +} + void createFooter(String footerPath) { const int kGitRevisionLength = 10; - ProcessResult gitResult = Process.runSync('git', ['rev-parse', 'HEAD']); + final ProcessResult gitResult = Process.runSync('git', ['rev-parse', 'HEAD']); if (gitResult.exitCode != 0) throw 'git rev-parse exit with non-zero exit code: ${gitResult.exitCode}'; String gitRevision = gitResult.stdout.trim(); - gitResult = Process.runSync('git', ['status', '-b', '--porcelain']); - if (gitResult.exitCode != 0) - throw 'git status exit with non-zero exit code: ${gitResult.exitCode}'; - final Match gitBranchMatch = gitBranchRegexp.firstMatch( - gitResult.stdout.trim().split('\n').first); - final String gitBranchOut = gitBranchMatch == null ? '' : '• ${gitBranchMatch.group(1).split('...').first}'; + final String gitBranch = getBranchName(); + final String gitBranchOut = gitBranch.isEmpty ? '' : '• $gitBranch'; gitRevision = gitRevision.length > kGitRevisionLength ? gitRevision.substring(0, kGitRevisionLength) : gitRevision; @@ -256,6 +263,21 @@ void createFooter(String footerPath) { gitBranchOut].join(' ')); } +/// Generates an OpenSearch XML description that can be used to add a custom +/// search for Flutter API docs to the browser. Unfortunately, it has to know +/// the URL to which site to search, so we customize it here based upon the +/// branch name. +void createSearchMetadata(String templatePath, String metadataPath) { + final String template = File(templatePath).readAsStringSync(); + final String branch = getBranchName(); + final String metadata = template.replaceAll( + '{SITE_URL}', + branch == 'stable' ? 'https://docs.flutter.io/' : 'https://master-docs.flutter.io/', + ); + Directory(path.dirname(metadataPath)).create(recursive: true); + File(metadataPath).writeAsStringSync(metadata); +} + /// Recursively copies `srcDir` to `destDir`, invoking [onFileCopied], if /// specified, for each source/destination file pair. /// @@ -292,7 +314,8 @@ void copyAssets() { (File src, File dest) => print('Copied ${src.path} to ${dest.path}')); } - +/// Clean out any existing snippets so that we don't publish old files from +/// previous runs accidentally. void cleanOutSnippets() { final Directory snippetsDir = Directory(path.join(kPublishRoot, 'snippets')); if (snippetsDir.existsSync()) {