Improve phpDocs auto-generation

.travis.yml

@@ -24,18 +24,17 @@ script:
 
 after_success:
   - |
-    [[ ",$DEPLOY_PHPDOC_BRANCHES," == *,"$TRAVIS_BRANCH",* ]] && [ "$TRAVIS_PHP_VERSION" == "5.3" ] && (
+    [ "$TRAVIS_PHP_VERSION" != "5.3" ] && echo "Skipping phpDoc deployment because this is not on the required runtime" && exit
-      [ "$TRAVIS_SECURE_ENV_VARS" == "true" ] && [ -z "$TRAVIS_TAG" ] && (
+    [[ ",$DEPLOY_PHPDOC_BRANCHES," != *,"$TRAVIS_BRANCH",* ]] && echo "Skipping phpDoc deployment because this branch is not permitted to deploy" && exit
-        ./build/generate-phpdoc.sh . "build/phpdoc-master" "Pico 1.0 API Documentation (master)"
+    [ "$TRAVIS_SECURE_ENV_VARS" != "true" ] && echo "Skipping phpDoc deployment because this is no environment with write access to the repository" && exit
-        ./build/deploy-phpdoc.sh "$TRAVIS_REPO_SLUG" "build/phpdoc-master" "master@$TRAVIS_COMMIT" "phpDoc/master" "gh-pages"
+    ./build/generate-phpdoc.sh "$TRAVIS_BUILD_DIR" "$TRAVIS_BUILD_DIR/build/phpdoc-master" "Pico 1.0 API Documentation (master)"
-      )
+    ./build/deploy-phpdoc.sh "$TRAVIS_REPO_SLUG" "$TRAVIS_BUILD_DIR/build/phpdoc-master" "master @ $TRAVIS_COMMIT" "phpDoc/master" "gh-pages"
-    )
 
 before_deploy:
   - |
     [ "$DEPLOY_PHPDOC_TAGS" == "true" ] && (
-      ./build/generate-phpdoc.sh . "build/phpdoc-$TRAVIS_TAG" "Pico 1.0 API Documentation ($TRAVIS_TAG)"
+      ./build/generate-phpdoc.sh "$TRAVIS_BUILD_DIR" "$TRAVIS_BUILD_DIR/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"
+      ./build/deploy-phpdoc.sh "$TRAVIS_REPO_SLUG" "$TRAVIS_BUILD_DIR/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

@@ -26,10 +26,10 @@ echo
 if git check-ref-format "tags/$SOURCE_REF"; then
     SOURCE_REF_TYPE="tag"
     SOURCE_REF_TAG="$SOURCE_REF"
-elif [[ "$SOURCE_REF" == *@* ]]; then
+elif [[ "$SOURCE_REF" == *" @ "* ]]; then
     SOURCE_REF_TYPE="commit"
-    SOURCE_REF_BRANCH="${SOURCE_REF%@*}"
+    SOURCE_REF_BRANCH="${SOURCE_REF% @ *}"
-    SOURCE_REF_COMMIT="${SOURCE_REF##*@}"
+    SOURCE_REF_COMMIT="${SOURCE_REF##* @ }"
 
     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
@@ -67,7 +67,7 @@ cp -R "$SOURCE_DIR" "$TARGET_DIR"
 # commit changes
 printf '\nCommiting changes...\n'
 git add --all "$TARGET_DIR"
-git commit -m "Add phpDocumentor class docs for $SOURCE_REF"
+git commit -m "Update phpDocumentor class docs for $SOURCE_REF"
 
 # very simple race condition protection for concurrent Travis builds
 # this is no definite protection (race conditions are still possible during `git push`),

build/generate-phpdoc.sh

@@ -15,8 +15,9 @@ echo
 
 # generate phpdoc
 phpdoc -d "$PHPDOC_SOURCE_DIR" \
-    -i 'build/*' -i 'vendor/*' -i 'plugins/*' \
+    -i 'build/*' \
-    -f 'plugins/DummyPlugin.php' \
+    -i 'vendor/*' \
+    -i 'plugins/*' -f 'plugins/DummyPlugin.php' \
     -t "$PHPDOC_TARGET_DIR" \
     --title "$PHPDOC_TITLE"