From f3a4f7e86da61243d3012ee5229302ba2e73172d Mon Sep 17 00:00:00 2001 From: Greg Spencer Date: Tue, 13 Nov 2018 15:58:06 -0800 Subject: [PATCH] Generate a zip file of offline docs and a Dash/Zeal docset. (#24244) This generates a zip file containing all of the docs, and uploads it when we publish docs, as well as a Dash/Zeal docset that contains a feed of the docs. Addresses at least part of #9955 --- dev/bots/docs.sh | 52 ++++++++++++++++++- dev/ci/docker_linux/Dockerfile | 13 ++++- dev/docs/dashing.json.tmpl | 91 ++++++++++++++++++++++++++++++++++ 3 files changed, 153 insertions(+), 3 deletions(-) create mode 100644 dev/docs/dashing.json.tmpl diff --git a/dev/bots/docs.sh b/dev/bots/docs.sh index 144a78c147..6a3088ecf2 100755 --- a/dev/bots/docs.sh +++ b/dev/bots/docs.sh @@ -30,6 +30,42 @@ function script_location() { echo "$(cd -P "$(dirname "$script_location")" >/dev/null && pwd)" } +# Zip up the docs so people can download them for offline usage. +function create_offline_zip() { + # Must be run from "$FLUTTER_ROOT/dev/docs" + echo "Zipping Flutter offline docs archive." + 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 Dashing produces a LOT of output + # (~30MB), so we redirect it, and just show the end of it if there was a + # problem. + echo "Building Flutter docset." + rm -rf flutter.docset + sed -e "s/{{VERSION}}/$FLUTTER_VERSION/g" dashing.json.tmpl > dashing.json && \ + (dashing build --source ./doc --config ./dashing.json > /tmp/dashing.log 2>&1 || (tail -100 /tmp/dashing.log; false)) && \ + tar cf flutter.docset.tar.gz --use-compress-program="gzip --best" flutter.docset +} + +function move_offline_into_place() { + # Must be run from "$FLUTTER_ROOT/dev/docs" + echo "Moving offline data into place." + mkdir -p doc/offline + mv flutter.docs.zip doc/offline/flutter.docs.zip + du -sh doc/offline/flutter.docs.zip + if [[ "$CIRRUS_BRANCH" == "stable" ]]; then + echo -e "\n ${FLUTTER_VERSION}\n https://docs.flutter.io/offline/flutter.docset.tar.gz\n" > doc/offline/flutter.xml + else + echo -e "\n ${FLUTTER_VERSION}\n https://master-docs-flutter-io.firebaseapp.com/offline/flutter.docset.tar.gz\n" > doc/offline/flutter.xml + fi + mv flutter.docset.tar.gz doc/offline/flutter.docset.tar.gz + du -sh doc/offline/flutter.docset.tar.gz +} + # 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 @@ -53,12 +89,13 @@ export PATH="$FLUTTER_BIN:$DART_BIN:$PATH" # Make sure dart is installed by invoking flutter to download it. "$FLUTTER" --version +FLUTTER_VERSION=$(cat "$FLUTTER_ROOT/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 ".". + # This has to be exported, because pub interprets setting it to the empty + # string in the same way as setting it to ".". export PUB_CACHE="${PUB_CACHE:-"$FLUTTER_PUB_CACHE"}" fi @@ -72,6 +109,17 @@ fi (cd "$FLUTTER_ROOT" && "$DART" "$FLUTTER_ROOT/dev/tools/dartdoc.dart") (cd "$FLUTTER_ROOT" && "$DART" "$FLUTTER_ROOT/dev/tools/java_and_objc_doc.dart") +# Zip up the docs so people can download them for offline usage. +(cd "$FLUTTER_ROOT/dev/docs"; create_offline_zip) + +# Generate the docset for Flutter docs for use with Dash, Zeal, and Velocity. +(cd "$FLUTTER_ROOT/dev/docs"; create_docset) + +# Move the offline archives into place, now that all the processing of the doc +# directory is done. This avoids the tools recursively processing the archives +# as part of their process. +(cd "$FLUTTER_ROOT/dev/docs"; move_offline_into_place) + # Ensure google webmaster tools can verify our site. cp "$FLUTTER_ROOT/dev/docs/google2ed1af765c529f57.html" "$FLUTTER_ROOT/dev/docs/doc" diff --git a/dev/ci/docker_linux/Dockerfile b/dev/ci/docker_linux/Dockerfile index 461220dc3d..8f0e546059 100644 --- a/dev/ci/docker_linux/Dockerfile +++ b/dev/ci/docker_linux/Dockerfile @@ -21,6 +21,7 @@ RUN apt-get install -y --no-install-recommends \ git \ wget \ curl \ + zip \ unzip \ ca-certificates \ gnupg @@ -34,6 +35,7 @@ RUN bash "${NODEJS_INSTALL}/nodejs_install.sh" # Install the rest of the dependencies. RUN apt-get install -y --no-install-recommends \ locales \ + golang \ ruby \ ruby-dev \ nodejs \ @@ -82,13 +84,22 @@ ENV PATH="$GRADLE_ROOT/bin:$PATH" ENV PATH="/usr/bin:${PATH}" RUN dpkg-query -L nodejs # Install Firebase -RUN /usr/bin/npm install -g git://github.com/firebase/firebase-tools.git +# This is why we need nodejs installed. +RUN /usr/bin/npm --verbose install -g firebase-tools + +# Install dashing +# This is why we need golang installed. +RUN mkdir -p /opt/gopath/bin +ENV GOPATH=/opt/gopath +ENV PATH="${GOPATH}/bin:${PATH}" +RUN go get -u github.com/technosophos/dashing # Set locale to en_US RUN locale-gen en_US "en_US.UTF-8" && dpkg-reconfigure locales ENV LANG en_US.UTF-8 # Install coveralls and Firebase +# This is why we need ruby installed. RUN gem install coveralls RUN gem install bundler diff --git a/dev/docs/dashing.json.tmpl b/dev/docs/dashing.json.tmpl new file mode 100644 index 0000000000..09ade889f4 --- /dev/null +++ b/dev/docs/dashing.json.tmpl @@ -0,0 +1,91 @@ +{ + "name": "flutter", + "package": "flutter", + "version": "{{VERSION}}", + "author": { + "name": "The Flutter Team", + "link": "https://flutter.io" + }, + "index": "index.html", + "selectors": { + "#exceptions span.name a": { + "type": "Exception" + }, + + "body > main > div.col-xs-12.col-sm-9.col-md-8.main-content > h1": { + "requiretext": " library", + "type": "Library", + "regexp": " library", + "replacement": "" + }, + + "body > main > div.col-xs-12.col-sm-9.main-content > h1": { + "requiretext": " class", + "type": "Class", + "regexp": " class", + "replacement": "" + }, + + "body > main > div.col-xs-12.col-md-8.main-content > h1": { + "requiretext": " function", + "type": "Function", + "regexp": " function", + "replacement": "" + }, + + "body > main > div.col-sm-9.col-md-8.main-content > h1": { + "requiretext": " typedef", + "type": "Type", + "regexp": " typedef", + "replacement": "" + }, + + "body > main > .col-xs-12.col-sm-9.col-md-8.main-content > h1": { + "requiretext": " enum", + "type": "Enum", + "regexp": " enum", + "replacement": "" + }, + + "body > main > .col-md-8.main-content > h1": { + "requiretext": " constant", + "type": "Constant", + "regexp": " constant", + "replacement": "" + }, + + "body > main > div.col-xs-12.col-sm-9 > h1": { + "requiretext": " method", + "type": "Method", + "regexp": " method", + "replacement": "" + }, + + "body > main > .col-xs-12.col-sm-9.col-md-8 > h1": { + "requiretext": " property", + "type": "Property", + "regexp": " property", + "replacement": "" + }, + + "body > main > .col-xs-12.col-md-8 > h1": { + "requiretext": " constructor", + "type": "Constructor", + "regexp": " constructor", + "replacement": "" + }, + + "body > main > .col-xs-12.col-sm-9.main-content > h1": { + "requiretext": "operator ", + "type": "Operator", + "regexp": "operator ", + "replacement": "" + } + }, + "ignore": [ + "ABOUT" + ], + "icon32x32": "icon.png", + "allowJS": true, + "ExternalURL": "https://docs.flutter.io" +}