Ian Hickson | 449f4a6 | 2019-11-27 15:04:02 -0800 | [diff] [blame] | 1 | #!/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 Ladd | 1ac08b2 | 2016-07-12 12:53:47 -0700 | [diff] [blame] | 6 | set -e |
Devon Carew | cd8f65d | 2016-05-02 14:33:39 -0700 | [diff] [blame] | 7 | |
Greg Spencer | 77645df | 2018-08-06 17:33:31 -0700 | [diff] [blame] | 8 | function 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 Spencer | 10e4b04 | 2021-08-11 19:48:29 -0700 | [diff] [blame] | 16 | cd -P "$(dirname "$script_location")" >/dev/null && pwd |
Greg Spencer | 77645df | 2018-08-06 17:33:31 -0700 | [diff] [blame] | 17 | } |
| 18 | |
Todd Volkert | 8e0eee9 | 2020-07-26 23:38:01 -0700 | [diff] [blame] | 19 | function generate_docs() { |
| 20 | # Install and activate dartdoc. |
Michael Goderbauer | 923eb76 | 2020-09-22 12:57:13 -0700 | [diff] [blame] | 21 | # NOTE: When updating to a new dartdoc version, please also update |
| 22 | # `dartdoc_options.yaml` to include newly introduced error and warning types. |
Michael Goderbauer | 49a52ae | 2022-07-06 16:24:08 -0700 | [diff] [blame] | 23 | "$DART" pub global activate dartdoc 6.0.0 |
Greg Spencer | 10e4b04 | 2021-08-11 19:48:29 -0700 | [diff] [blame] | 24 | |
| 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 Goderbauer | 0a5a641 | 2022-05-13 14:49:26 -0700 | [diff] [blame] | 28 | "$DART" pub global activate snippets 0.3.0 |
Todd Volkert | 8e0eee9 | 2020-07-26 23:38:01 -0700 | [diff] [blame] | 29 | |
| 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 Spencer | a7310dc | 2021-08-30 12:16:05 -0700 | [diff] [blame] | 33 | (cd "$FLUTTER_ROOT/dev/tools" && "$DART" pub get) |
Michael Goderbauer | 3e867f7 | 2020-08-18 19:11:05 -0700 | [diff] [blame] | 34 | (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 Volkert | 8e0eee9 | 2020-07-26 23:38:01 -0700 | [diff] [blame] | 36 | } |
| 37 | |
Greg Spencer | f20adcc | 2018-11-15 15:05:57 -0800 | [diff] [blame] | 38 | # Zip up the docs so people can download them for offline usage. |
| 39 | function create_offline_zip() { |
| 40 | # Must be run from "$FLUTTER_ROOT/dev/docs" |
Todd Volkert | 81bf39e | 2020-07-24 22:38:17 -0700 | [diff] [blame] | 41 | echo "$(date): Zipping Flutter offline docs archive." |
Greg Spencer | f20adcc | 2018-11-15 15:05:57 -0800 | [diff] [blame] | 42 | 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. |
| 47 | function create_docset() { |
| 48 | # Must be run from "$FLUTTER_ROOT/dev/docs" |
| 49 | # Must have dashing installed: go get -u github.com/technosophos/dashing |
Greg Spencer | 02dbb08 | 2019-01-25 08:48:52 -0800 | [diff] [blame] | 50 | # 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 Volkert | 81bf39e | 2020-07-24 22:38:17 -0700 | [diff] [blame] | 52 | echo "$(date): Building Flutter docset." |
Greg Spencer | f20adcc | 2018-11-15 15:05:57 -0800 | [diff] [blame] | 53 | rm -rf flutter.docset |
Christopher Fujino | e3ad034 | 2020-07-01 19:41:41 -0700 | [diff] [blame] | 54 | # If dashing gets stuck, Cirrus will time out the build after an hour, and we |
Todd Volkert | 35e7005 | 2020-07-25 09:44:17 -0700 | [diff] [blame] | 55 | # 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 Volkert | 39fa002 | 2020-07-27 21:11:43 -0700 | [diff] [blame] | 57 | dashing_log=/tmp/dashing.log |
| 58 | dashing build --source ./doc --config ./dashing.json > $dashing_log 2>&1 & |
Todd Volkert | 35e7005 | 2020-07-25 09:44:17 -0700 | [diff] [blame] | 59 | dashing_pid=$! |
Todd Volkert | 35e7005 | 2020-07-25 09:44:17 -0700 | [diff] [blame] | 60 | wait $dashing_pid && \ |
Greg Spencer | 625a37b | 2018-12-11 09:53:33 -0800 | [diff] [blame] | 61 | cp ./doc/flutter/static-assets/favicon.png ./flutter.docset/icon.png && \ |
Michael Goderbauer | 3e867f7 | 2020-08-18 19:11:05 -0700 | [diff] [blame] | 62 | "$DART" --disable-dart-dev --enable-asserts ./dashing_postprocess.dart && \ |
Todd Volkert | 39fa002 | 2020-07-27 21:11:43 -0700 | [diff] [blame] | 63 | 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 Spencer | f20adcc | 2018-11-15 15:05:57 -0800 | [diff] [blame] | 69 | } |
| 70 | |
Todd Volkert | 8e0eee9 | 2020-07-26 23:38:01 -0700 | [diff] [blame] | 71 | function deploy_docs() { |
godofredoc | f8f6963 | 2020-10-13 17:06:49 -0700 | [diff] [blame] | 72 | case "$LUCI_BRANCH" in |
Todd Volkert | 8e0eee9 | 2020-07-26 23:38:01 -0700 | [diff] [blame] | 73 | master) |
godofredoc | f8f6963 | 2020-10-13 17:06:49 -0700 | [diff] [blame] | 74 | echo "$(date): Updating $LUCI_BRANCH docs: https://master-api.flutter.dev/" |
Todd Volkert | 8e0eee9 | 2020-07-26 23:38:01 -0700 | [diff] [blame] | 75 | # 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 Volkert | 8e0eee9 | 2020-07-26 23:38:01 -0700 | [diff] [blame] | 78 | ;; |
| 79 | stable) |
godofredoc | f8f6963 | 2020-10-13 17:06:49 -0700 | [diff] [blame] | 80 | echo "$(date): Updating $LUCI_BRANCH docs: https://api.flutter.dev/" |
Todd Volkert | 8e0eee9 | 2020-07-26 23:38:01 -0700 | [diff] [blame] | 81 | # 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 Volkert | 8e0eee9 | 2020-07-26 23:38:01 -0700 | [diff] [blame] | 84 | ;; |
| 85 | *) |
godofredoc | f8f6963 | 2020-10-13 17:06:49 -0700 | [diff] [blame] | 86 | >&2 echo "Docs deployment cannot be run on the $LUCI_BRANCH branch." |
Christopher Fujino | d6e308c | 2020-08-19 18:16:05 -0700 | [diff] [blame] | 87 | exit 0 |
Todd Volkert | 8e0eee9 | 2020-07-26 23:38:01 -0700 | [diff] [blame] | 88 | esac |
| 89 | } |
| 90 | |
Greg Spencer | f20adcc | 2018-11-15 15:05:57 -0800 | [diff] [blame] | 91 | # 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. |
| 94 | function move_offline_into_place() { |
| 95 | # Must be run from "$FLUTTER_ROOT/dev/docs" |
Todd Volkert | 81bf39e | 2020-07-24 22:38:17 -0700 | [diff] [blame] | 96 | echo "$(date): Moving offline data into place." |
Greg Spencer | f20adcc | 2018-11-15 15:05:57 -0800 | [diff] [blame] | 97 | mkdir -p doc/offline |
| 98 | mv flutter.docs.zip doc/offline/flutter.docs.zip |
| 99 | du -sh doc/offline/flutter.docs.zip |
godofredoc | f8f6963 | 2020-10-13 17:06:49 -0700 | [diff] [blame] | 100 | if [[ "$LUCI_BRANCH" == "stable" ]]; then |
Greg Spencer | 10e4b04 | 2021-08-11 19:48:29 -0700 | [diff] [blame] | 101 | 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 |
godofredoc | f8f6963 | 2020-10-13 17:06:49 -0700 | [diff] [blame] | 102 | else |
Greg Spencer | 10e4b04 | 2021-08-11 19:48:29 -0700 | [diff] [blame] | 103 | 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 |
godofredoc | f8f6963 | 2020-10-13 17:06:49 -0700 | [diff] [blame] | 104 | fi |
| 105 | mv flutter.docset.tar.gz doc/offline/flutter.docset.tar.gz |
| 106 | du -sh doc/offline/flutter.docset.tar.gz |
Greg Spencer | f20adcc | 2018-11-15 15:05:57 -0800 | [diff] [blame] | 107 | } |
| 108 | |
Greg Spencer | 77645df | 2018-08-06 17:33:31 -0700 | [diff] [blame] | 109 | # So that users can run this script from anywhere and it will work as expected. |
| 110 | SCRIPT_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. |
| 114 | FLUTTER_ROOT="$(dirname "$(dirname "$SCRIPT_LOCATION")")" |
| 115 | |
Todd Volkert | 8c5c720 | 2020-07-28 01:07:42 -0700 | [diff] [blame] | 116 | echo "$(date): Running docs.sh" |
Ian Hickson | 45e8114 | 2018-01-30 09:00:57 -0800 | [diff] [blame] | 117 | |
Greg Spencer | 77645df | 2018-08-06 17:33:31 -0700 | [diff] [blame] | 118 | if [[ ! -d "$FLUTTER_ROOT" || ! -f "$FLUTTER_ROOT/bin/flutter" ]]; then |
Todd Volkert | 8e0eee9 | 2020-07-26 23:38:01 -0700 | [diff] [blame] | 119 | >&2 echo "Unable to locate the Flutter installation (using FLUTTER_ROOT: $FLUTTER_ROOT)" |
Greg Spencer | 77645df | 2018-08-06 17:33:31 -0700 | [diff] [blame] | 120 | exit 1 |
| 121 | fi |
Ian Hickson | 127545a | 2017-05-06 15:08:14 -0700 | [diff] [blame] | 122 | |
Greg Spencer | 77645df | 2018-08-06 17:33:31 -0700 | [diff] [blame] | 123 | FLUTTER_BIN="$FLUTTER_ROOT/bin" |
| 124 | DART_BIN="$FLUTTER_ROOT/bin/cache/dart-sdk/bin" |
| 125 | FLUTTER="$FLUTTER_BIN/flutter" |
| 126 | DART="$DART_BIN/dart" |
Greg Spencer | 77645df | 2018-08-06 17:33:31 -0700 | [diff] [blame] | 127 | export PATH="$FLUTTER_BIN:$DART_BIN:$PATH" |
Greg Spencer | 711ecf7 | 2018-07-30 12:35:15 -0700 | [diff] [blame] | 128 | |
Greg Spencer | 10e4b04 | 2021-08-11 19:48:29 -0700 | [diff] [blame] | 129 | # Make sure dart is installed by invoking Flutter to download it. |
| 130 | # This also creates the 'version' file. |
| 131 | FLUTTER_VERSION=$("$FLUTTER" --version --machine) |
| 132 | export FLUTTER_VERSION |
| 133 | FLUTTER_VERSION_STRING=$(cat "$FLUTTER_ROOT/version") |
Ian Hickson | 1e6c7eb | 2017-05-11 09:42:08 -0700 | [diff] [blame] | 134 | |
Greg Spencer | f29ecba | 2017-12-05 14:46:39 -0800 | [diff] [blame] | 135 | # If the pub cache directory exists in the root, then use that. |
| 136 | FLUTTER_PUB_CACHE="$FLUTTER_ROOT/.pub-cache" |
Greg Spencer | 77645df | 2018-08-06 17:33:31 -0700 | [diff] [blame] | 137 | if [[ -d "$FLUTTER_PUB_CACHE" ]]; then |
Greg Spencer | f20adcc | 2018-11-15 15:05:57 -0800 | [diff] [blame] | 138 | # This has to be exported, because pub interprets setting it to the empty |
| 139 | # string in the same way as setting it to ".". |
Greg Spencer | f29ecba | 2017-12-05 14:46:39 -0800 | [diff] [blame] | 140 | export PUB_CACHE="${PUB_CACHE:-"$FLUTTER_PUB_CACHE"}" |
| 141 | fi |
| 142 | |
Todd Volkert | 8c5c720 | 2020-07-28 01:07:42 -0700 | [diff] [blame] | 143 | generate_docs |
Christopher Fujino | d6e308c | 2020-08-19 18:16:05 -0700 | [diff] [blame] | 144 | # Skip publishing docs for PRs and release candidate branches |
godofredoc | f8f6963 | 2020-10-13 17:06:49 -0700 | [diff] [blame] | 145 | if [[ -n "$LUCI_CI" && -z "$LUCI_PR" ]]; then |
Christopher Fujino | d6e308c | 2020-08-19 18:16:05 -0700 | [diff] [blame] | 146 | (cd "$FLUTTER_ROOT/dev/docs"; create_offline_zip) |
godofredoc | f8f6963 | 2020-10-13 17:06:49 -0700 | [diff] [blame] | 147 | (cd "$FLUTTER_ROOT/dev/docs"; create_docset) |
Christopher Fujino | d6e308c | 2020-08-19 18:16:05 -0700 | [diff] [blame] | 148 | (cd "$FLUTTER_ROOT/dev/docs"; move_offline_into_place) |
| 149 | deploy_docs |
Todd Volkert | 8c5c720 | 2020-07-28 01:07:42 -0700 | [diff] [blame] | 150 | fi |
godofredoc | 1545b04 | 2022-12-14 13:02:37 -0800 | [diff] [blame] | 151 | |
| 152 | # Zip docs |
| 153 | cd "$FLUTTER_ROOT/dev/docs" |
godofredoc | 1443d95 | 2022-12-19 08:57:01 -0800 | [diff] [blame] | 154 | zip -r api_docs.zip doc |