Refactor phpDoc deployment

This should prevent empty phpDoc updates like 55b4a2b

.gitignore

@@ -19,7 +19,6 @@ desktop.ini
 /_build/phpdoc/
 /_build/phpdoc.cache/
 /_build/phpdoc-*/
-/_build/phpdoc-*.git/
 
 # User config
 /config/config.php

_build/deploy-phpdoc-branch.sh

@@ -16,15 +16,27 @@ if [ "$TRAVIS_PULL_REQUEST" != "false" ]; then
 fi
 
 PHPDOC_ID="${TRAVIS_BRANCH//\//_}"
+PHPDOC_GIT_DIR="$TRAVIS_BUILD_DIR/_build/phpdoc-$PHPDOC_ID.git"
+PHPDOC_CACHE_DIR="$PHPDOC_GIT_DIR/phpdoc/$PHPDOC_ID.cache"
+PHPDOC_TARGET_DIR="$PHPDOC_GIT_DIR/phpdoc/$PHPDOC_ID"
 
+# clone repo
+echo "Cloning repo..."
+git clone --branch="gh-pages" "https://github.com/$TRAVIS_REPO_SLUG.git" "$PHPDOC_GIT_DIR"
+[ $? -eq 0 ] || exit 1
+
+cd "$PHPDOC_GIT_DIR"
+echo
+
+# generate phpDocs
 generate-phpdoc.sh \
     "$TRAVIS_BUILD_DIR/.phpdoc.xml" \
-    "$TRAVIS_BUILD_DIR/_build/phpdoc.cache" \
-    "$TRAVIS_BUILD_DIR/_build/phpdoc-$PHPDOC_ID" \
+    "$PHPDOC_CACHE_DIR" "$PHPDOC_TARGET_DIR" \
     "Pico 1.0 API Documentation ($TRAVIS_BRANCH branch)"
 [ $? -eq 0 ] || exit 1
 
+# deploy phpDocs
 deploy-phpdoc.sh \
-    "$TRAVIS_REPO_SLUG" "heads/$TRAVIS_BRANCH @ $TRAVIS_COMMIT" "$TRAVIS_BUILD_DIR/_build/phpdoc-$PHPDOC_ID" \
-    "$TRAVIS_REPO_SLUG" "gh-pages" "phpDoc/$PHPDOC_ID"
+    "Update phpDocumentor class docs for $TRAVIS_BRANCH branch @ $TRAVIS_COMMIT" \
+    "$TRAVIS_REPO_SLUG" "heads/$TRAVIS_BRANCH" "$TRAVIS_COMMIT"
 [ $? -eq 0 ] || exit 1

_build/deploy-phpdoc-release.sh

@@ -3,15 +3,27 @@
 [ "$DEPLOY_PHPDOC_RELEASES" == "true" ] || exit
 
 PHPDOC_ID="${TRAVIS_BRANCH//\//_}"
+PHPDOC_GIT_DIR="$TRAVIS_BUILD_DIR/_build/phpdoc-$PHPDOC_ID.git"
+PHPDOC_CACHE_DIR="$TRAVIS_BUILD_DIR/_build/phpdoc-$PHPDOC_ID.cache"
+PHPDOC_TARGET_DIR="$PHPDOC_GIT_DIR/phpdoc/$PHPDOC_ID"
 
+# clone repo
+echo "Cloning repo..."
+git clone --branch="gh-pages" "https://github.com/$TRAVIS_REPO_SLUG.git" "$PHPDOC_GIT_DIR"
+[ $? -eq 0 ] || exit 1
+
+cd "$PHPDOC_GIT_DIR"
+echo
+
+# generate phpDocs
 generate-phpdoc.sh \
     "$TRAVIS_BUILD_DIR/.phpdoc.xml" \
-    "$TRAVIS_BUILD_DIR/_build/phpdoc.cache" \
-    "$TRAVIS_BUILD_DIR/_build/phpdoc-$PHPDOC_ID" \
+    "$PHPDOC_CACHE_DIR" "$PHPDOC_TARGET_DIR" \
     "Pico 1.0 API Documentation ($TRAVIS_TAG)"
 [ $? -eq 0 ] || exit 1
 
+# deploy phpDocs
 deploy-phpdoc.sh \
-    "$TRAVIS_REPO_SLUG" "tags/$TRAVIS_TAG" "$TRAVIS_BUILD_DIR/_build/phpdoc-$PHPDOC_ID" \
-    "$TRAVIS_REPO_SLUG" "gh-pages" "phpDoc/$PHPDOC_ID"
+    "Update phpDocumentor class docs for $TRAVIS_TAG" \
+    "$TRAVIS_REPO_SLUG" "tags/$TRAVIS_TAG" "$TRAVIS_COMMIT"
 [ $? -eq 0 ] || exit 1

_build/deploy-phpdoc.sh

@@ -1,56 +1,32 @@
 #!/usr/bin/env bash
 set -e
 
-# base variables
-APP_NAME="$(basename "$0")"
-BASE_PWD="$PWD"
-
 # environment variables
 # GITHUB_OAUTH_TOKEN    GitHub authentication token, see https://github.com/settings/tokens
 
 # parameters
-SOURCE_REPO_SLUG="$1"       # source GitHub repo (e.g. picocms/Pico)
-SOURCE_REF="$2"             # source reference (either "[ref] @ [commit]" or "[ref]",
-                            #                   [ref] can be e.g. heads/master or tags/v1.0.0)
-SOURCE_DIR="$3"             # absolute source path
-TARGET_REPO_SLUG="$4"       # target GitHub repo (e.g. picocms/Pico)
-TARGET_BRANCH="$5"          # target branch (e.g. gh-pages)
-TARGET_DIR="$6"             # relative target path
+COMMIT_MESSAGE="$1"         # commit message
+CHECK_REPO_SLUG="$2"        # optional GitHub repo (e.g. picocms/Pico) to check
+                            # its latest commit as basic race condition protection
+CHECK_REMOTE_REF="$3"       # optional remote Git reference (e.g. heads/master)
+CHECK_LOCAL_COMMIT="$4"     # optional local commit SHA1
 
 # print parameters
 echo "Deploying phpDocs..."
-printf 'SOURCE_REPO_SLUG="%s"\n' "$SOURCE_REPO_SLUG"
-printf 'SOURCE_REF="%s"\n' "$SOURCE_REF"
-printf 'SOURCE_DIR="%s"\n' "$SOURCE_DIR"
-printf 'TARGET_REPO_SLUG="%s"\n' "$TARGET_REPO_SLUG"
-printf 'TARGET_BRANCH="%s"\n' "$TARGET_BRANCH"
-printf 'TARGET_DIR="%s"\n' "$TARGET_DIR"
+printf 'COMMIT_MESSAGE="%s"\n' "$COMMIT_MESSAGE"
+printf 'CHECK_REPO_SLUG="%s"\n' "$CHECK_REPO_SLUG"
+printf 'CHECK_REMOTE_REF="%s"\n' "$CHECK_REMOTE_REF"
+printf 'CHECK_LOCAL_COMMIT="%s"\n' "$CHECK_LOCAL_COMMIT"
 echo
 
-# evaluate source reference
-if [[ "$SOURCE_REF" == *" @ "* ]]; then
-    SOURCE_REF_TYPE="commit"
-    SOURCE_REF_HEAD="${SOURCE_REF% @ *}"
-    SOURCE_REF_COMMIT="${SOURCE_REF##* @ }"
-
-    if ! git check-ref-format "$SOURCE_REF_HEAD" || ! git rev-parse --verify "$SOURCE_REF_COMMIT" > /dev/null; then
-        echo "FATAL: $APP_NAME source reference '$SOURCE_REF' is invalid" >&2
-        exit 1
-    fi
-elif git check-ref-format "$SOURCE_REF"; then
-    SOURCE_REF_TYPE="ref"
-else
-    echo "FATAL: $APP_NAME source reference '$SOURCE_REF' is invalid" >&2
-    exit 1
+# check for changes
+if [ -z "$(git status --porcelain)" ]; then
+    echo "Nothing to deploy; skipping..."
+    exit 0
 fi
 
-# clone repo
-printf 'Cloning repo...\n'
-GIT_DIR="$SOURCE_DIR.git"
-git clone --branch="$TARGET_BRANCH" "https://github.com/$TARGET_REPO_SLUG.git" "$GIT_DIR"
-
 # setup git
-cd "$GIT_DIR"
+printf 'Preparing repo...\n'
 git config user.name "Travis CI"
 git config user.email "travis-ci@picocms.org"
 
@@ -59,35 +35,29 @@ if [ -n "$GITHUB_OAUTH_TOKEN" ]; then
     (umask 077 && echo "https://GitHub:$GITHUB_OAUTH_TOKEN@github.com" > .git/credentials)
 fi
 
-# copy phpdoc
-printf '\nCopying phpDocs...\n'
-[ ! -d "$TARGET_DIR" ] || rm -rf "$TARGET_DIR"
-[ "${SOURCE_DIR:0:1}" == "/" ] || SOURCE_DIR="$BASE_PWD/$SOURCE_DIR"
-cp -R "$SOURCE_DIR" "$TARGET_DIR"
-
 # commit changes
 printf '\nCommiting changes...\n'
-git add --all "$TARGET_DIR"
-git commit --message="Update phpDocumentor class docs for $SOURCE_REF"
+git add --all
+git commit --message="$COMMIT_MESSAGE"
 
-# very simple race condition protection for concurrent Travis builds
+# race condition protection for concurrent Travis builds
 # this is no definite protection (race conditions are still possible during `git push`),
 # but it should give a basic protection without disabling concurrent builds completely
-if [ "$SOURCE_REF_TYPE" == "commit" ]; then
-    # load branch data via GitHub APIv3
-    printf '\nRetrieving latest commit...\n'
-    LATEST_COMMIT_URL="https://api.github.com/repos/$SOURCE_REPO_SLUG/git/refs/$SOURCE_REF_HEAD"
+if [ -n "$CHECK_REPO_SLUG" ] && [ -n "$CHECK_REMOTE_REF" ] && [ -n "$CHECK_LOCAL_COMMIT" ]; then
+    # retrieve information using GitHub APIv3
+    printf '\nChecking latest commit...\n'
+    CHECK_API_URL="https://api.github.com/repos/$CHECK_REPO_SLUG/git/refs/$CHECK_REMOTE_REF"
     if [ -n "$GITHUB_OAUTH_TOKEN" ]; then
-        LATEST_COMMIT_RESPONSE="$(wget -O- --header="Authorization: token $GITHUB_OAUTH_TOKEN" "$LATEST_COMMIT_URL" 2> /dev/null)"
+        CHECK_API_RESPONSE="$(wget -O- --header="Authorization: token $GITHUB_OAUTH_TOKEN" "$CHECK_API_URL" 2> /dev/null)"
     else
-        LATEST_COMMIT_RESPONSE="$(wget -O- "$LATEST_COMMIT_URL" 2> /dev/null)"
+        CHECK_API_RESPONSE="$(wget -O- "$CHECK_API_URL" 2> /dev/null)"
     fi
 
     # evaluate JSON response
-    LATEST_COMMIT="$(echo "$LATEST_COMMIT_RESPONSE" | php -r "
+    CHECK_REMOTE_COMMIT="$(echo "$CHECK_API_RESPONSE" | php -r "
         \$json = json_decode(stream_get_contents(STDIN), true);
         if (\$json !== null) {
-            if (isset(\$json['ref']) && (\$json['ref'] === 'refs/$SOURCE_REF_HEAD')) {
+            if (isset(\$json['ref']) && (\$json['ref'] === 'refs/$CHECK_REMOTE_REF')) {
                 if (isset(\$json['object']) && isset(\$json['object']['sha'])) {
                     echo \$json['object']['sha'];
                 }
@@ -96,14 +66,14 @@ if [ "$SOURCE_REF_TYPE" == "commit" ]; then
     ")"
 
     # compare source reference against the latest commit
-    if [ "$LATEST_COMMIT" != "$SOURCE_REF_COMMIT" ]; then
-        echo "WARNING: $APP_NAME source reference '$SOURCE_REF' doesn't match the latest commit '$LATEST_COMMIT'" >&2
+    if [ "$CHECK_REMOTE_COMMIT" != "$CHECK_LOCAL_COMMIT" ]; then
+        echo "WARNING: latest local commit '$CHECK_LOCAL_COMMIT' doesn't match latest remote commit '$CHECK_REMOTE_COMMIT'" >&2
         exit 0
     fi
 fi
 
 # push changes
 printf '\nPushing changes...\n'
-git push "https://github.com/$TARGET_REPO_SLUG.git" "$TARGET_BRANCH:$TARGET_BRANCH"
+git push origin
 
 echo

_build/generate-phpdoc.sh

@@ -2,10 +2,10 @@
 set -e
 
 # parameters
-PHPDOC_CONFIG="$1"
-PHPDOC_CACHE_DIR="$2"
-PHPDOC_TARGET_DIR="$3"
-PHPDOC_TITLE="$4"
+PHPDOC_CONFIG="$1"          # phpDoc config file
+PHPDOC_CACHE_DIR="$2"       # phpDoc cache dir
+PHPDOC_TARGET_DIR="$3"      # phpDoc output dir
+PHPDOC_TITLE="$4"           # API docs title
 
 # print parameters
 echo "Generating phpDocs..."
@@ -15,8 +15,24 @@ printf 'PHPDOC_TARGET_DIR="%s"\n' "$PHPDOC_TARGET_DIR"
 printf 'PHPDOC_TITLE="%s"\n' "$PHPDOC_TITLE"
 echo
 
-# generate phpdoc
-phpdoc --config "$PHPDOC_CONFIG" \
+# parse phpDoc files (i.e. update cache)
+printf "\nUpdate phpDoc cache...\n"
+phpdoc project:parse --config "$PHPDOC_CONFIG" \
+    --target "$PHPDOC_CACHE_DIR"
+
+# check for changes
+printf '\nCheck for phpDoc cache changes...\n'
+if [ -z "$(git status --porcelain "$PHPDOC_CACHE_DIR")" ]; then
+    echo "No changes detected, don't rewrite phpDoc API docs..."
+    exit 0
+fi
+
+# transform phpDoc files (i.e. rewrite API docs)
+# NOTE: actually this should be `phpdoc project:transform`,
+#       but the command seems to be broken...
+printf '\nRewrite phpDoc API docs...\n'
+rm -rf "$PHPDOC_TARGET_DIR"
+phpdoc project:run --config "$PHPDOC_CONFIG" \
     --cache-folder "$PHPDOC_CACHE_DIR" \
     --target "$PHPDOC_TARGET_DIR" \
     --title "$PHPDOC_TITLE"