docs.sh 6.91 KB
Newer Older
Ian Hickson's avatar
Ian Hickson committed
1 2 3 4 5
#!/usr/bin/env bash
# Copyright 2014 The Flutter Authors. All rights reserved.
# Use of this source code is governed by a BSD-style license that can be
# found in the LICENSE file.

6
set -e
7

8 9 10 11
function deploy {
  local total_tries="$1"
  local remaining_tries=$(($total_tries - 1))
  shift
12
  while [[ "$remaining_tries" -gt 0 ]]; do
13
    (cd "$FLUTTER_ROOT/dev/docs" && firebase --debug deploy --token "$FIREBASE_TOKEN" --project "$@") && break
14 15 16 17 18 19 20
    remaining_tries=$(($remaining_tries - 1))
    echo "Error: Unable to deploy documentation to Firebase. Retrying in five seconds... ($remaining_tries tries left)"
    sleep 5
  done

  [[ "$remaining_tries" == 0 ]] && {
    echo "Command still failed after $total_tries tries: '$@'"
21
    cat firebase-debug.log || echo "Unable to show contents of firebase-debug.log."
Ian Hickson's avatar
Ian Hickson committed
22
    return 1
23 24 25 26 27 28 29 30 31 32 33 34 35 36 37
  }
  return 0
}

function script_location() {
  local script_location="${BASH_SOURCE[0]}"
  # Resolve symlinks
  while [[ -h "$script_location" ]]; do
    DIR="$(cd -P "$( dirname "$script_location")" >/dev/null && pwd)"
    script_location="$(readlink "$script_location")"
    [[ "$script_location" != /* ]] && script_location="$DIR/$script_location"
  done
  echo "$(cd -P "$(dirname "$script_location")" >/dev/null && pwd)"
}

38 39
function generate_docs() {
    # Install and activate dartdoc.
40
    "$PUB" global activate dartdoc 0.32.4
41 42 43 44 45

    # This script generates a unified doc set, and creates
    # a custom index.html, placing everything into dev/docs/doc.
    (cd "$FLUTTER_ROOT/dev/tools" && "$FLUTTER" pub get)
    (cd "$FLUTTER_ROOT/dev/tools" && "$PUB" get)
46 47
    (cd "$FLUTTER_ROOT" && "$DART" --disable-dart-dev --enable-asserts "$FLUTTER_ROOT/dev/tools/dartdoc.dart")
    (cd "$FLUTTER_ROOT" && "$DART" --disable-dart-dev --enable-asserts "$FLUTTER_ROOT/dev/tools/java_and_objc_doc.dart")
48 49
}

50 51 52
# Zip up the docs so people can download them for offline usage.
function create_offline_zip() {
  # Must be run from "$FLUTTER_ROOT/dev/docs"
53
  echo "$(date): Zipping Flutter offline docs archive."
54 55 56 57 58 59 60 61
  rm -rf flutter.docs.zip doc/offline
  (cd ./doc; zip -r -9 -q ../flutter.docs.zip .)
}

# Generate the docset for Flutter docs for use with Dash, Zeal, and Velocity.
function create_docset() {
  # Must be run from "$FLUTTER_ROOT/dev/docs"
  # Must have dashing installed: go get -u github.com/technosophos/dashing
62 63
  # Dashing produces a LOT of log output (~30MB), so we redirect it, and just
  # show the end of it if there was a problem.
64
  echo "$(date): Building Flutter docset."
65
  rm -rf flutter.docset
66
  # If dashing gets stuck, Cirrus will time out the build after an hour, and we
67 68
  # never get to see the logs. Thus, we run it in the background and tail the logs
  # while we wait for it to complete.
69 70
  dashing_log=/tmp/dashing.log
  dashing build --source ./doc --config ./dashing.json > $dashing_log 2>&1 &
71 72
  dashing_pid=$!
  wait $dashing_pid && \
73
  cp ./doc/flutter/static-assets/favicon.png ./flutter.docset/icon.png && \
74
  "$DART" --disable-dart-dev --enable-asserts ./dashing_postprocess.dart && \
75 76 77 78 79 80
  tar cf flutter.docset.tar.gz --use-compress-program="gzip --best" flutter.docset
  if [[ $? -ne 0 ]]; then
      >&2 echo "Dashing docset generation failed"
      tail -200 $dashing_log
      exit 1
  fi
81 82
}

83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104
function deploy_docs() {
    # Ensure google webmaster tools can verify our site.
    cp "$FLUTTER_ROOT/dev/docs/google2ed1af765c529f57.html" "$FLUTTER_ROOT/dev/docs/doc"

    case "$CIRRUS_BRANCH" in
        master)
            echo "$(date): Updating $CIRRUS_BRANCH docs: https://master-api.flutter.dev/"
            # 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"
            export FIREBASE_TOKEN="$FIREBASE_MASTER_TOKEN"
            deploy 5 master-docs-flutter-dev
            ;;
        stable)
            echo "$(date): Updating $CIRRUS_BRANCH docs: https://api.flutter.dev/"
            # Enable search indexing on the master staging site so searches get only
            # the stable site.
            echo -e "# All robots welcome!" > "$FLUTTER_ROOT/dev/docs/doc/robots.txt"
            export FIREBASE_TOKEN="$FIREBASE_PUBLIC_TOKEN"
            deploy 5 docs-flutter-dev
            ;;
        *)
105
            >&2 echo "Docs deployment cannot be run on the $CIRRUS_BRANCH branch."
106
            exit 0
107 108 109
    esac
}

110 111 112 113 114
# Move the offline archives into place, after all the processing of the doc
# directory is done. This avoids the tools recursively processing the archives
# as part of their process.
function move_offline_into_place() {
  # Must be run from "$FLUTTER_ROOT/dev/docs"
115
  echo "$(date): Moving offline data into place."
116 117 118
  mkdir -p doc/offline
  mv flutter.docs.zip doc/offline/flutter.docs.zip
  du -sh doc/offline/flutter.docs.zip
119 120 121 122 123 124 125 126
  # TODO(tvolkert): re-enable (https://github.com/flutter/flutter/issues/60646)
  # if [[ "$CIRRUS_BRANCH" == "stable" ]]; then
  #   echo -e "<entry>\n  <version>${FLUTTER_VERSION}</version>\n  <url>https://api.flutter.dev/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-api.flutter.dev/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
127 128
}

129 130 131 132 133 134 135
# So that users can run this script from anywhere and it will work as expected.
SCRIPT_LOCATION="$(script_location)"
# Sets the Flutter root to be "$(script_location)/../..": This script assumes
# that it resides two directory levels down from the root, so if that changes,
# then this line will need to as well.
FLUTTER_ROOT="$(dirname "$(dirname "$SCRIPT_LOCATION")")"

136
echo "$(date): Running docs.sh"
137

138
if [[ ! -d "$FLUTTER_ROOT" || ! -f "$FLUTTER_ROOT/bin/flutter" ]]; then
139
  >&2 echo "Unable to locate the Flutter installation (using FLUTTER_ROOT: $FLUTTER_ROOT)"
140 141
  exit 1
fi
Ian Hickson's avatar
Ian Hickson committed
142

143 144 145 146 147 148
FLUTTER_BIN="$FLUTTER_ROOT/bin"
DART_BIN="$FLUTTER_ROOT/bin/cache/dart-sdk/bin"
FLUTTER="$FLUTTER_BIN/flutter"
DART="$DART_BIN/dart"
PUB="$DART_BIN/pub"
export PATH="$FLUTTER_BIN:$DART_BIN:$PATH"
149

150 151
# Make sure dart is installed by invoking flutter to download it.
"$FLUTTER" --version
152
FLUTTER_VERSION=$(cat "$FLUTTER_ROOT/version")
153

154 155
# If the pub cache directory exists in the root, then use that.
FLUTTER_PUB_CACHE="$FLUTTER_ROOT/.pub-cache"
156
if [[ -d "$FLUTTER_PUB_CACHE" ]]; then
157 158
  # This has to be exported, because pub interprets setting it to the empty
  # string in the same way as setting it to ".".
159 160 161
  export PUB_CACHE="${PUB_CACHE:-"$FLUTTER_PUB_CACHE"}"
fi

162
generate_docs
163
# Skip publishing docs for PRs and release candidate branches
164
if [[ -n "$CIRRUS_CI" && -z "$CIRRUS_PR" ]]; then
165 166 167 168 169
  (cd "$FLUTTER_ROOT/dev/docs"; create_offline_zip)
  # TODO(tvolkert): re-enable (https://github.com/flutter/flutter/issues/60646)
  # (cd "$FLUTTER_ROOT/dev/docs"; create_docset)
  (cd "$FLUTTER_ROOT/dev/docs"; move_offline_into_place)
  deploy_docs
170
fi