1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
#!/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.
set -e
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
cd -P "$(dirname "$script_location")" >/dev/null && pwd
}
# 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")")"
export FLUTTER_ROOT
echo "$(date): Running docs.sh"
if [[ ! -d "$FLUTTER_ROOT" || ! -f "$FLUTTER_ROOT/bin/flutter" ]]; then
>&2 echo "Unable to locate the Flutter installation (using FLUTTER_ROOT: $FLUTTER_ROOT)"
exit 1
fi
FLUTTER_BIN="$FLUTTER_ROOT/bin"
DART_BIN="$FLUTTER_ROOT/bin/cache/dart-sdk/bin"
FLUTTER="$FLUTTER_BIN/flutter"
DART="$DART_BIN/dart"
PATH="$FLUTTER_BIN:$DART_BIN:$PATH"
# Make sure dart is installed by invoking Flutter to download it if it is missing.
# Also make sure the flutter command is ready to run before capturing output from
# it: if it has to rebuild itself or something, it'll spoil our JSON output.
"$FLUTTER" > /dev/null 2>&1
FLUTTER_VERSION="$("$FLUTTER" --version --machine)"
export FLUTTER_VERSION
# If the pub cache directory exists in the root, then use that.
FLUTTER_PUB_CACHE="$FLUTTER_ROOT/.pub-cache"
if [[ -d "$FLUTTER_PUB_CACHE" ]]; then
# This has to be exported, because pub interprets setting it to the empty
# string in the same way as setting it to ".".
PUB_CACHE="${PUB_CACHE:-"$FLUTTER_PUB_CACHE"}"
export PUB_CACHE
fi
function usage() {
echo "Usage: $(basename "${BASH_SOURCE[0]}") [--keep-temp] [--output <output.zip>]"
echo ""
echo " --keep-staging Do not delete the staging directory created while generating"
echo " docs. Normally the script deletes the staging directory after"
echo " generating the output ZIP file."
echo " --output <output.zip> specifies where the output ZIP file containing the documentation"
echo " data will be written."
echo " --staging-dir <directory> specifies where the temporary output files will be written while"
echo " generating docs. This directory will be deleted after generation"
echo " unless --keep-staging is also specified."
echo ""
}
function parse_args() {
local arg
local args=()
STAGING_DIR=
KEEP_STAGING=0
DESTINATION="$FLUTTER_ROOT/dev/docs/api_docs.zip"
while (( "$#" )); do
case "$1" in
--help)
usage
exit 0
;;
--staging-dir)
STAGING_DIR="$2"
shift
;;
--keep-staging)
KEEP_STAGING=1
;;
--output)
DESTINATION="$2"
shift
;;
*)
args=("${args[@]}" "$1")
;;
esac
shift
done
if [[ -z $STAGING_DIR ]]; then
STAGING_DIR=$(mktemp -d /tmp/dartdoc.XXXXX)
fi
DOC_DIR="$STAGING_DIR/doc"
if [[ ${#args[@]} != 0 ]]; then
>&2 echo "ERROR: Unknown arguments: ${args[@]}"
usage
exit 1
fi
}
function generate_docs() {
# Install and activate dartdoc.
# When updating to a new dartdoc version, please also update
# `dartdoc_options.yaml` to include newly introduced error and warning types.
"$DART" pub global activate dartdoc 8.0.2
# Install and activate the snippets tool, which resides in the
# assets-for-api-docs repo:
# https://github.com/flutter/assets-for-api-docs/tree/master/packages/snippets
"$DART" pub global activate snippets 0.4.0
# This script generates a unified doc set, and creates
# a custom index.html, placing everything into DOC_DIR.
# Make sure that create_api_docs.dart has all the dependencies it needs.
(cd "$FLUTTER_ROOT/dev/tools" && "$FLUTTER" pub get)
(cd "$FLUTTER_ROOT" && "$DART" --disable-dart-dev --enable-asserts "$FLUTTER_ROOT/dev/tools/create_api_docs.dart" --output-dir="$DOC_DIR")
}
function main() {
echo "Writing docs build temporary output to $DOC_DIR"
mkdir -p "$DOC_DIR"
generate_docs
# If the destination isn't an absolute path, make it into one.
if ! [[ "$DESTINATION" =~ ^/ ]]; then
DESTINATION="$PWD/$DESTINATION"
fi
# Make sure the destination has .zip as an extension, because zip will add it
# anyhow, and we want to print the correct output location.
DESTINATION=${DESTINATION%.zip}.zip
# Zip up doc directory and write the output to the destination.
(cd "$STAGING_DIR"; zip -r -9 -q "$DESTINATION" ./doc)
if [[ $KEEP_STAGING -eq 1 ]]; then
echo "Staging documentation output left in $STAGING_DIR"
else
echo "Removing staging documentation output from $STAGING_DIR"
rm -rf "$STAGING_DIR"
fi
echo "Wrote docs ZIP file to $DESTINATION"
}
parse_args "$@"
main