Adds favicon to Dash/Zeal docset, adds OpenSearch metadata. (#25178)

This sets the favicon for the offline Dash/Zeal docs.

Also, sets up the OpenSearch Description metadata file so that people can create custom search shortcuts for the API docs site.

Fixes #6412

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 "<entry>\n  <version>${FLUTTER_VERSION}</version>\n  <url>https://docs.flutter.io/offline/flutter.docset.tar.gz</url>\n</entry>" > doc/offline/flutter.xml
   else
-    echo -e "<entry>\n  <version>${FLUTTER_VERSION}</version>\n  <url>https://master-docs-flutter-io.firebaseapp.com/offline/flutter.docset.tar.gz</url>\n</entry>" > doc/offline/flutter.xml
+    echo -e "<entry>\n  <version>${FLUTTER_VERSION}</version>\n  <url>https://master-docs.flutter.io/offline/flutter.docset.tar.gz</url>\n</entry>" > 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"

dev/docs/lib/opensearch.xml

@@ -0,0 +1,14 @@
+<OpenSearchDescription xmlns="http://a9.com/-/spec/opensearch/1.1/" xmlns:moz="http://www.mozilla.org/2006/browser/search/">
+<ShortName>Flutter API</ShortName>
+<Description>
+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.
+</Description>
+<InputEncoding>UTF-8</InputEncoding>
+<Image width="32" height="32" type="image/x-icon">/flutter/static-assets/favicon.png</Image>
+<Url type="text/html" method="get" template="{SITE_URL}?search={searchTerms}"/>
+</OpenSearchDescription>

dev/docs/opensearch.html

@@ -0,0 +1 @@
+<link rel="search" type="application/opensearchdescription+xml" title="Flutter API" href="/opensearch.xml"/>

dev/tools/dartdoc.dart

@@ -100,6 +100,7 @@ Future<void> main(List<String> arguments) async {
 
   createFooter('$kDocsRoot/lib/footer.html');
   copyAssets();
+  createSearchMetadata('$kDocsRoot/lib/opensearch.xml', '$kDocsRoot/doc/opensearch.xml');
   cleanOutSnippets();
 
   final List<String> dartdocBaseArgs = <String>['global', 'run'];
@@ -134,6 +135,7 @@ Future<void> main(List<String> arguments) async {
     '--header', 'analytics.html',
     '--header', 'survey.html',
     '--header', 'snippets.html',
+    '--header', 'opensearch.html',
     '--footer-text', 'lib/footer.html',
     '--exclude-packages',
     <String>[
@@ -231,20 +233,25 @@ ArgParser _createArgsParser() {
 
 final RegExp gitBranchRegexp = RegExp(r'^## (.*)');
 
+String getBranchName() {
+  final ProcessResult gitResult = Process.runSync('git', <String>['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', <String>['rev-parse', 'HEAD']);
+  final ProcessResult gitResult = Process.runSync('git', <String>['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', <String>['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 ? '' : '• </span class="no-break">${gitBranchMatch.group(1).split('...').first}</span>';
+  final String gitBranch = getBranchName();
+  final String gitBranchOut = gitBranch.isEmpty ? '' : '• </span class="no-break">$gitBranch</span>';
 
   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()) {