From 3852585ba0b1b4b6bee95217b261c1ddfc5e73b8 Mon Sep 17 00:00:00 2001
From: Daniel Rudolf <github.com@daniel-rudolf.de>
Date: Wed, 25 Nov 2015 21:55:28 +0100
Subject: [PATCH] Improve phpDocs auto-generation

---
 .travis.yml              | 10 ++++------
 build/deploy-phpdoc.sh   | 16 ++++++++++++----
 build/generate-phpdoc.sh |  9 ++++++++-
 3 files changed, 24 insertions(+), 11 deletions(-)

diff --git a/.travis.yml b/.travis.yml
index 9212024..a613974 100644
--- a/.travis.yml
+++ b/.travis.yml
@@ -26,18 +26,16 @@ after_success:
   - |
     [[ ",$DEPLOY_PHPDOC_BRANCHES," == *,"$TRAVIS_BRANCH",* ]] && [ "$TRAVIS_PHP_VERSION" == "5.3" ] && (
       [ "$TRAVIS_SECURE_ENV_VARS" == "true" ] && [ -z "$TRAVIS_TAG" ] && (
-        ./build/generate-phpdoc.sh . "$TRAVIS_BUILD_DIR/build/phpdoc-master" "Pico 1.0 API Documentation (master@$TRAVIS_COMMIT)"
-        printf '\n'
-        ./build/deploy-phpdoc.sh "$TRAVIS_REPO_SLUG" "$TRAVIS_BUILD_DIR/build/phpdoc-master" "master@$TRAVIS_COMMIT" "phpDoc/master" "gh-pages"
+        ./build/generate-phpdoc.sh . "build/phpdoc-master" "Pico 1.0 API Documentation (master)"
+        ./build/deploy-phpdoc.sh "$TRAVIS_REPO_SLUG" "build/phpdoc-master" "master@$TRAVIS_COMMIT" "phpDoc/master" "gh-pages"
       )
     )
 
 before_deploy:
   - |
     [ "$DEPLOY_PHPDOC_TAGS" == "true" ] && (
-      ./build/generate-phpdoc.sh . "$TRAVIS_BUILD_DIR/build/phpdoc-$TRAVIS_TAG" "Pico 1.0 API Documentation ($TRAVIS_TAG)"
-      printf '\n'
-      ./build/deploy-phpdoc.sh "$TRAVIS_REPO_SLUG" "$TRAVIS_BUILD_DIR/build/phpdoc-$TRAVIS_TAG" "$TRAVIS_TAG" "phpDoc/$TRAVIS_TAG" "gh-pages"
+      ./build/generate-phpdoc.sh . "build/phpdoc-$TRAVIS_TAG" "Pico 1.0 API Documentation ($TRAVIS_TAG)"
+      ./build/deploy-phpdoc.sh "$TRAVIS_REPO_SLUG" "build/phpdoc-$TRAVIS_TAG" "$TRAVIS_TAG" "phpDoc/$TRAVIS_TAG" "gh-pages"
     )
   - composer install --no-dev --optimize-autoloader
   - tar -czf "pico-release-$TRAVIS_TAG.tar.gz" README.md LICENSE CONTRIBUTING.md CHANGELOG.md composer.json composer.lock config content-sample lib plugins themes vendor .htaccess index.php
diff --git a/build/deploy-phpdoc.sh b/build/deploy-phpdoc.sh
index 44d7424..f68d1dd 100755
--- a/build/deploy-phpdoc.sh
+++ b/build/deploy-phpdoc.sh
@@ -13,7 +13,13 @@ SOURCE_REF="$3"             # source reference (either [branch]@[commit], [branc
 TARGET_DIR="$4"             # relative target path
 TARGET_BRANCH="$5"          # target branch (e.g. gh-pages)
 
-printf 'Deploying phpDocs (%s (%s) --> %s:%s/%s)...\n' "$SOURCE_DIR" "$SOURCE_REF" "$GITHUB_SLUG" "$TARGET_BRANCH" "$TARGET_DIR"
+# print parameters
+echo "Deploying phpDocs..."
+printf 'GITHUB_SLUG="%s"\n' "$GITHUB_SLUG"
+printf 'SOURCE_DIR="%s"\n' "$SOURCE_DIR"
+printf 'SOURCE_REF="%s"\n' "$SOURCE_REF"
+printf 'TARGET_DIR="%s"\n' "$TARGET_DIR"
+printf 'TARGET_BRANCH="%s"\n' "$TARGET_BRANCH"
 
 # evaluate target reference
 if git check-ref-format "tags/$SOURCE_REF"; then
@@ -24,7 +30,7 @@ elif [[ "$SOURCE_REF" == *@* ]]; then
     SOURCE_REF_BRANCH="${SOURCE_REF%@*}"
     SOURCE_REF_COMMIT="${SOURCE_REF##*@}"
 
-    if ! git check-ref-format "heads/$SOURCE_REF_BRANCH"; then
+    if ! git check-ref-format "heads/$SOURCE_REF_BRANCH" || ! git rev-parse --verify "$SOURCE_REF_COMMIT"; then
         echo "FATAL: $APP_NAME target reference '$SOURCE_REF' is invalid" >&2
         exit 1
     fi
@@ -37,7 +43,7 @@ else
 fi
 
 # clone repo
-printf '\nCloning %s branch of %s...\n' "$TARGET_BRANCH" "https://github.com/$GITHUB_SLUG.git"
+printf '\nCloning repo...\n'
 GIT_DIR="$SOURCE_DIR.git"
 git clone -b "$TARGET_BRANCH" "https://github.com/$GITHUB_SLUG.git" "$GIT_DIR"
 
@@ -48,9 +54,9 @@ git config user.email "travis-ci@picocms.org"
 [ -n "$GITHUB_OAUTH_TOKEN" ] && git config credential.https://github.com.username "$GITHUB_OAUTH_TOKEN"
 
 # copy phpdoc
+printf '\nCopying phpDocs...\n'
 [ ! -d "$TARGET_DIR" ] || rm -rf "$TARGET_DIR"
 [ "${SOURCE_DIR:0:1}" == "/" ] || SOURCE_DIR="$BASE_PWD/$SOURCE_DIR"
-printf '\nCopying phpDoc (%s --> %s)...\n' "$SOURCE_DIR" "$GIT_DIR/$TARGET_DIR"
 cp -R "$SOURCE_DIR" "$TARGET_DIR"
 
 # commit changes
@@ -85,3 +91,5 @@ fi
 # push changes
 printf '\nPushing changes...\n'
 git push "https://github.com/$GITHUB_SLUG.git" "$TARGET_BRANCH:$TARGET_BRANCH"
+
+echo
diff --git a/build/generate-phpdoc.sh b/build/generate-phpdoc.sh
index 0cbad7b..83fef3f 100755
--- a/build/generate-phpdoc.sh
+++ b/build/generate-phpdoc.sh
@@ -6,10 +6,17 @@ PHPDOC_SOURCE_DIR="$1"
 PHPDOC_TARGET_DIR="$2"
 PHPDOC_TITLE="$3"
 
+# print parameters
+echo "Generating phpDocs..."
+printf 'PHPDOC_SOURCE_DIR="%s"\n' "$PHPDOC_SOURCE_DIR"
+printf 'PHPDOC_TARGET_DIR="%s"\n' "$PHPDOC_TARGET_DIR"
+printf 'PHPDOC_TITLE="%s"\n' "$PHPDOC_TITLE"
+
 # generate phpdoc
-printf 'Generating phpDocs (%s --> %s; "%s")...\n' "$PHPDOC_SOURCE_DIR" "$PHPDOC_TARGET_DIR" "$PHPDOC_TITLE"
 phpdoc -d "$PHPDOC_SOURCE_DIR" \
     -i 'build/*' -i 'vendor/*' -i 'plugins/*' \
     -f 'plugins/DummyPlugin.php' \
     -t "$PHPDOC_TARGET_DIR" \
     --title "$PHPDOC_TITLE"
+
+echo