Improve phpDocs auto-generation

.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

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

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