blob: a25e5f5ab385ff863fbaff68747adce8e2f5587e [file] [log] [blame]
Ian Hickson449f4a62019-11-27 15:04:02 -08001#!/usr/bin/env bash
2# Copyright 2014 The Flutter Authors. All rights reserved.
3# Use of this source code is governed by a BSD-style license that can be
4# found in the LICENSE file.
5
Seth Ladd1ac08b22016-07-12 12:53:47 -07006set -e
Devon Carewcd8f65d2016-05-02 14:33:39 -07007
Greg Spencer77645df2018-08-06 17:33:31 -07008function script_location() {
9 local script_location="${BASH_SOURCE[0]}"
10 # Resolve symlinks
11 while [[ -h "$script_location" ]]; do
12 DIR="$(cd -P "$( dirname "$script_location")" >/dev/null && pwd)"
13 script_location="$(readlink "$script_location")"
14 [[ "$script_location" != /* ]] && script_location="$DIR/$script_location"
15 done
Greg Spencer10e4b042021-08-11 19:48:29 -070016 cd -P "$(dirname "$script_location")" >/dev/null && pwd
Greg Spencer77645df2018-08-06 17:33:31 -070017}
18
Todd Volkert8e0eee92020-07-26 23:38:01 -070019function generate_docs() {
20 # Install and activate dartdoc.
Michael Goderbauer923eb762020-09-22 12:57:13 -070021 # NOTE: When updating to a new dartdoc version, please also update
22 # `dartdoc_options.yaml` to include newly introduced error and warning types.
Michael Goderbauer49a52ae2022-07-06 16:24:08 -070023 "$DART" pub global activate dartdoc 6.0.0
Greg Spencer10e4b042021-08-11 19:48:29 -070024
25 # Install and activate the snippets tool, which resides in the
26 # assets-for-api-docs repo:
27 # https://github.com/flutter/assets-for-api-docs/tree/master/packages/snippets
Michael Goderbauer0a5a6412022-05-13 14:49:26 -070028 "$DART" pub global activate snippets 0.3.0
Todd Volkert8e0eee92020-07-26 23:38:01 -070029
30 # This script generates a unified doc set, and creates
31 # a custom index.html, placing everything into dev/docs/doc.
32 (cd "$FLUTTER_ROOT/dev/tools" && "$FLUTTER" pub get)
Greg Spencera7310dc2021-08-30 12:16:05 -070033 (cd "$FLUTTER_ROOT/dev/tools" && "$DART" pub get)
Michael Goderbauer3e867f72020-08-18 19:11:05 -070034 (cd "$FLUTTER_ROOT" && "$DART" --disable-dart-dev --enable-asserts "$FLUTTER_ROOT/dev/tools/dartdoc.dart")
35 (cd "$FLUTTER_ROOT" && "$DART" --disable-dart-dev --enable-asserts "$FLUTTER_ROOT/dev/tools/java_and_objc_doc.dart")
Todd Volkert8e0eee92020-07-26 23:38:01 -070036}
37
Greg Spencerf20adcc2018-11-15 15:05:57 -080038# Zip up the docs so people can download them for offline usage.
39function create_offline_zip() {
40 # Must be run from "$FLUTTER_ROOT/dev/docs"
Todd Volkert81bf39e2020-07-24 22:38:17 -070041 echo "$(date): Zipping Flutter offline docs archive."
Greg Spencerf20adcc2018-11-15 15:05:57 -080042 rm -rf flutter.docs.zip doc/offline
43 (cd ./doc; zip -r -9 -q ../flutter.docs.zip .)
44}
45
46# Generate the docset for Flutter docs for use with Dash, Zeal, and Velocity.
47function create_docset() {
48 # Must be run from "$FLUTTER_ROOT/dev/docs"
49 # Must have dashing installed: go get -u github.com/technosophos/dashing
Greg Spencer02dbb082019-01-25 08:48:52 -080050 # Dashing produces a LOT of log output (~30MB), so we redirect it, and just
51 # show the end of it if there was a problem.
Todd Volkert81bf39e2020-07-24 22:38:17 -070052 echo "$(date): Building Flutter docset."
Greg Spencerf20adcc2018-11-15 15:05:57 -080053 rm -rf flutter.docset
Christopher Fujinoe3ad0342020-07-01 19:41:41 -070054 # If dashing gets stuck, Cirrus will time out the build after an hour, and we
Todd Volkert35e70052020-07-25 09:44:17 -070055 # never get to see the logs. Thus, we run it in the background and tail the logs
56 # while we wait for it to complete.
Todd Volkert39fa0022020-07-27 21:11:43 -070057 dashing_log=/tmp/dashing.log
58 dashing build --source ./doc --config ./dashing.json > $dashing_log 2>&1 &
Todd Volkert35e70052020-07-25 09:44:17 -070059 dashing_pid=$!
Todd Volkert35e70052020-07-25 09:44:17 -070060 wait $dashing_pid && \
Greg Spencer625a37b2018-12-11 09:53:33 -080061 cp ./doc/flutter/static-assets/favicon.png ./flutter.docset/icon.png && \
Michael Goderbauer3e867f72020-08-18 19:11:05 -070062 "$DART" --disable-dart-dev --enable-asserts ./dashing_postprocess.dart && \
Todd Volkert39fa0022020-07-27 21:11:43 -070063 tar cf flutter.docset.tar.gz --use-compress-program="gzip --best" flutter.docset
64 if [[ $? -ne 0 ]]; then
65 >&2 echo "Dashing docset generation failed"
66 tail -200 $dashing_log
67 exit 1
68 fi
Greg Spencerf20adcc2018-11-15 15:05:57 -080069}
70
Todd Volkert8e0eee92020-07-26 23:38:01 -070071function deploy_docs() {
godofredocf8f69632020-10-13 17:06:49 -070072 case "$LUCI_BRANCH" in
Todd Volkert8e0eee92020-07-26 23:38:01 -070073 master)
godofredocf8f69632020-10-13 17:06:49 -070074 echo "$(date): Updating $LUCI_BRANCH docs: https://master-api.flutter.dev/"
Todd Volkert8e0eee92020-07-26 23:38:01 -070075 # Disable search indexing on the master staging site so searches get only
76 # the stable site.
77 echo -e "User-agent: *\nDisallow: /" > "$FLUTTER_ROOT/dev/docs/doc/robots.txt"
Todd Volkert8e0eee92020-07-26 23:38:01 -070078 ;;
79 stable)
godofredocf8f69632020-10-13 17:06:49 -070080 echo "$(date): Updating $LUCI_BRANCH docs: https://api.flutter.dev/"
Todd Volkert8e0eee92020-07-26 23:38:01 -070081 # Enable search indexing on the master staging site so searches get only
82 # the stable site.
83 echo -e "# All robots welcome!" > "$FLUTTER_ROOT/dev/docs/doc/robots.txt"
Todd Volkert8e0eee92020-07-26 23:38:01 -070084 ;;
85 *)
godofredocf8f69632020-10-13 17:06:49 -070086 >&2 echo "Docs deployment cannot be run on the $LUCI_BRANCH branch."
Christopher Fujinod6e308c2020-08-19 18:16:05 -070087 exit 0
Todd Volkert8e0eee92020-07-26 23:38:01 -070088 esac
89}
90
Greg Spencerf20adcc2018-11-15 15:05:57 -080091# Move the offline archives into place, after all the processing of the doc
92# directory is done. This avoids the tools recursively processing the archives
93# as part of their process.
94function move_offline_into_place() {
95 # Must be run from "$FLUTTER_ROOT/dev/docs"
Todd Volkert81bf39e2020-07-24 22:38:17 -070096 echo "$(date): Moving offline data into place."
Greg Spencerf20adcc2018-11-15 15:05:57 -080097 mkdir -p doc/offline
98 mv flutter.docs.zip doc/offline/flutter.docs.zip
99 du -sh doc/offline/flutter.docs.zip
godofredocf8f69632020-10-13 17:06:49 -0700100 if [[ "$LUCI_BRANCH" == "stable" ]]; then
Greg Spencer10e4b042021-08-11 19:48:29 -0700101 echo -e "<entry>\n <version>${FLUTTER_VERSION_STRING}</version>\n <url>https://api.flutter.dev/offline/flutter.docset.tar.gz</url>\n</entry>" > doc/offline/flutter.xml
godofredocf8f69632020-10-13 17:06:49 -0700102 else
Greg Spencer10e4b042021-08-11 19:48:29 -0700103 echo -e "<entry>\n <version>${FLUTTER_VERSION_STRING}</version>\n <url>https://master-api.flutter.dev/offline/flutter.docset.tar.gz</url>\n</entry>" > doc/offline/flutter.xml
godofredocf8f69632020-10-13 17:06:49 -0700104 fi
105 mv flutter.docset.tar.gz doc/offline/flutter.docset.tar.gz
106 du -sh doc/offline/flutter.docset.tar.gz
Greg Spencerf20adcc2018-11-15 15:05:57 -0800107}
108
Greg Spencer77645df2018-08-06 17:33:31 -0700109# So that users can run this script from anywhere and it will work as expected.
110SCRIPT_LOCATION="$(script_location)"
111# Sets the Flutter root to be "$(script_location)/../..": This script assumes
112# that it resides two directory levels down from the root, so if that changes,
113# then this line will need to as well.
114FLUTTER_ROOT="$(dirname "$(dirname "$SCRIPT_LOCATION")")"
115
Todd Volkert8c5c7202020-07-28 01:07:42 -0700116echo "$(date): Running docs.sh"
Ian Hickson45e81142018-01-30 09:00:57 -0800117
Greg Spencer77645df2018-08-06 17:33:31 -0700118if [[ ! -d "$FLUTTER_ROOT" || ! -f "$FLUTTER_ROOT/bin/flutter" ]]; then
Todd Volkert8e0eee92020-07-26 23:38:01 -0700119 >&2 echo "Unable to locate the Flutter installation (using FLUTTER_ROOT: $FLUTTER_ROOT)"
Greg Spencer77645df2018-08-06 17:33:31 -0700120 exit 1
121fi
Ian Hickson127545a2017-05-06 15:08:14 -0700122
Greg Spencer77645df2018-08-06 17:33:31 -0700123FLUTTER_BIN="$FLUTTER_ROOT/bin"
124DART_BIN="$FLUTTER_ROOT/bin/cache/dart-sdk/bin"
125FLUTTER="$FLUTTER_BIN/flutter"
126DART="$DART_BIN/dart"
Greg Spencer77645df2018-08-06 17:33:31 -0700127export PATH="$FLUTTER_BIN:$DART_BIN:$PATH"
Greg Spencer711ecf72018-07-30 12:35:15 -0700128
Greg Spencer10e4b042021-08-11 19:48:29 -0700129# Make sure dart is installed by invoking Flutter to download it.
130# This also creates the 'version' file.
131FLUTTER_VERSION=$("$FLUTTER" --version --machine)
132export FLUTTER_VERSION
133FLUTTER_VERSION_STRING=$(cat "$FLUTTER_ROOT/version")
Ian Hickson1e6c7eb2017-05-11 09:42:08 -0700134
Greg Spencerf29ecba2017-12-05 14:46:39 -0800135# If the pub cache directory exists in the root, then use that.
136FLUTTER_PUB_CACHE="$FLUTTER_ROOT/.pub-cache"
Greg Spencer77645df2018-08-06 17:33:31 -0700137if [[ -d "$FLUTTER_PUB_CACHE" ]]; then
Greg Spencerf20adcc2018-11-15 15:05:57 -0800138 # This has to be exported, because pub interprets setting it to the empty
139 # string in the same way as setting it to ".".
Greg Spencerf29ecba2017-12-05 14:46:39 -0800140 export PUB_CACHE="${PUB_CACHE:-"$FLUTTER_PUB_CACHE"}"
141fi
142
Todd Volkert8c5c7202020-07-28 01:07:42 -0700143generate_docs
Christopher Fujinod6e308c2020-08-19 18:16:05 -0700144# Skip publishing docs for PRs and release candidate branches
godofredocf8f69632020-10-13 17:06:49 -0700145if [[ -n "$LUCI_CI" && -z "$LUCI_PR" ]]; then
Christopher Fujinod6e308c2020-08-19 18:16:05 -0700146 (cd "$FLUTTER_ROOT/dev/docs"; create_offline_zip)
godofredocf8f69632020-10-13 17:06:49 -0700147 (cd "$FLUTTER_ROOT/dev/docs"; create_docset)
Christopher Fujinod6e308c2020-08-19 18:16:05 -0700148 (cd "$FLUTTER_ROOT/dev/docs"; move_offline_into_place)
149 deploy_docs
Todd Volkert8c5c7202020-07-28 01:07:42 -0700150fi
godofredoc1545b042022-12-14 13:02:37 -0800151
152# Zip docs
153cd "$FLUTTER_ROOT/dev/docs"
godofredoc1443d952022-12-19 08:57:01 -0800154zip -r api_docs.zip doc