Complete jazzy-doc auto documentation feature (#133)

.travis.yml

@@ -43,6 +43,7 @@ matrix:
       osx_image: xcode9
       sudo: required
       env: SWIFT_SNAPSHOT=swift-DEVELOPMENT-SNAPSHOT-2017-08-15-a
+      env: JAZZY_ELIGIBLE=true
     - os: osx
       osx_image: xcode9.2
       sudo: required

README.md

@@ -84,7 +84,16 @@ Please note that Codecov is only leveraged when executing builds on the macOS pl
 ### Auto Jazzy Docs Build
 [Jazzy](https://github.com/realm/jazzy) provides automatic documentation construction. To simplify the process of updating public facing api/documentation, package builder can automate the creation and pushing of updated docs for a Pull Request.
 
-To indicate that documentation should be generated, add the `jazzy-doc` label to the Pull Request. Credentials must be provided through the environment variables GITHUB_USERNAME and GITHUB_PASSWORD, which should be defined in the Travis configuration for the repository.
+To indicate that documentation should be generated, add the `jazzy-doc` label to the Pull Request.
+
+In order for a PR to receive automatic documentation generation, the following must be configured:
+- The Travis configuration for the repository must define the following environment variables, specifying the credentials of a user that has sufficient permissions to push to PR branches:
+  - `GITHUB_USERNAME`
+  - `GITHUB_PASSWORD`
+  - `GITHUB_EMAIL`
+- The repository must have a `jazzy-doc` label defined
+- The `.travis.yaml` for the project must contain one macOS build with `env: JAZZY_ELIGIBLE=true`
+- The PR must have the `jazzy-doc` label applied
 
 Once the regular build has executed, Jazzy will be run for MacOS builds and the resulting documentation pushed to the PR branch in a new `[ci skip]` commit.
 

build-package.sh

@@ -55,11 +55,15 @@ if [ -z "$projectBuildDir" ]; then
   usage
 fi
 
+# Determine location of this script
+# Ref: https://stackoverflow.com/questions/59895/getting-the-source-directory-of-a-bash-script-from-within
+SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
+
 # Utility functions
 function sourceScript () {
   if [ -e "$1" ]; then
     source "$1"
-    echo "$2"
+    echo ">> Completed ${2}."
   fi
 }
 
@@ -81,7 +85,7 @@ projectName="$(basename $projectFolder)"
 echo ">> projectName: $projectName"
 
 # Install swift binaries based on OS
-source ./Package-Builder/install-swift.sh
+source ${SCRIPT_DIR}/install-swift.sh
 
 # Show path
 echo ">> PATH: $PATH"
@@ -119,18 +123,18 @@ fi
 if [ -e "${projectFolder}/Tests" ]; then
     echo ">> Testing Swift package..."
     # Execute OS specific pre-test steps
-    sourceScript "`find ${projectFolder} -path "*/${projectName}/${osName}/before_tests.sh" -not -path "*/Package-Builder/*" -not -path "*/Packages/*"`" ">> Completed ${osName} pre-tests steps."
+    sourceScript "`find ${projectFolder} -path "*/${projectName}/${osName}/before_tests.sh" -not -path "*/Package-Builder/*" -not -path "*/Packages/*"`" "${osName} pre-tests steps"
 
     # Execute common pre-test steps
-    sourceScript "`find ${projectFolder} -path "*/${projectName}/common/before_tests.sh" -not -path "*/Package-Builder/*" -not -path "*/Packages/*"`" ">> Completed common pre-tests steps."
+    sourceScript "`find ${projectFolder} -path "*/${projectName}/common/before_tests.sh" -not -path "*/Package-Builder/*" -not -path "*/Packages/*"`" "common pre-tests steps"
 
-    source ./Package-Builder/run_tests.sh
+    source ${SCRIPT_DIR}/run_tests.sh
 
     # Execute common post-test steps
-    sourceScript "`find ${projectFolder} -path "*/${projectName}/common/after_tests.sh" -not -path "*/Package-Builder/*" -not -path "*/Packages/*"`" ">> Completed common post-tests steps."
+    sourceScript "`find ${projectFolder} -path "*/${projectName}/common/after_tests.sh" -not -path "*/Package-Builder/*" -not -path "*/Packages/*"`" "common post-tests steps"
 
     # Execute OS specific post-test steps
-    sourceScript "`find ${projectFolder} -path "*/${projectName}/${osName}/after_tests.sh" -not -path "*/Package-Builder/*" -not -path "*/Packages/*"`" ">> Completed ${osName} post-tests steps."
+    sourceScript "`find ${projectFolder} -path "*/${projectName}/${osName}/after_tests.sh" -not -path "*/Package-Builder/*" -not -path "*/Packages/*"`" "${osName} post-tests steps"
 
     echo ">> Finished testing Swift package."
     echo
@@ -164,16 +168,21 @@ if [ "$(uname)" == "Darwin" ]; then
   if [ -e ${projectFolder}/.swift-codecov ]; then
       source ${projectFolder}/.swift-codecov
   else
-      sourceScript "${projectFolder}/Package-Builder/codecov.sh"
+      sourceScript "${SCRIPT_DIR}/codecov.sh" "codecov generation"
   fi
 fi
 
 # Generate jazzy docs (macOS) for Pull Requests that have the 'jazzy-doc' label.
 # The docs will be generated and pushed as a new [ci skip] commit to the PR branch.
+#
 # Suitable credentials are required for this purpose. These should be defined in
 # the repo's Travis configuration as GITHUB_USERNAME and GITHUB_PASSWORD.
 #
-if [ "$(uname)" == "Darwin" ] && [ "${TRAVIS_PULL_REQUEST}" != "false" ]; then
+# Additionally, the Travis build must have the JAZZY_ELIGIBLE environment variable
+# defined, and this should be defined on only one macOS build, to ensure that only
+# one build (per commit) produces a documentation commit.
+#
+if [ "$(uname)" == "Darwin" -a "${TRAVIS_PULL_REQUEST}" != "false" -a -n "${JAZZY_ELIGIBLE}" ]; then
     if  [ -n "${GITHUB_USERNAME}" -a -n "${GITHUB_PASSWORD}" ]; then
         echo "Checking PR for docs generation tag"
         # Obtain the label information for this PR from the GitHub. This is a JSON document describing each label
@@ -187,7 +196,7 @@ if [ "$(uname)" == "Darwin" ] && [ "${TRAVIS_PULL_REQUEST}" != "false" ]; then
         # Check if any of the labels contain the text 'jazzy-doc'
         if [[ $candidateTags == *"jazzy-doc"* ]]; then
             echo "Documentation tag jazzy-doc exists for this repo"
-            sourceScript "${projectFolder}/Package-Builder/jazzy.sh"
+            sourceScript "${SCRIPT_DIR}/jazzy.sh" "jazzy-doc generation"
         else
             echo "No jazzy-doc tag found"
         fi

jazzy.sh

@@ -14,31 +14,55 @@
 # limitations under the License.
 ##
 
-# Check that we have credentials
-if [ -z "${GITHUB_USERNAME}" ] && [ -z "${GITHUB_PASSWORD}" ]; then
+# Check that we have credentials. In addition to the username and password,
+# we require an e-mail address for configuring our user when pushing docs
+# updates back to Github.
+if [ -z "${GITHUB_USERNAME}" -o -z "${GITHUB_PASSWORD}" -o -z "${GITHUB_EMAIL}" ]; then
     echo "Supplied jazzy docs flag, but credentials were not provided."
-    echo "Expected: GITHUB_USER && GITHUB_PASSWORD Env variables."
+    echo "Expected: GITHUB_USER, GITHUB_PASSWORD and GITHUB_EMAIL Env variables."
     exit 1
 fi
 
-# Check if .jazzy.yaml exists in the root folder of the repo
-#cd ..
-export projectFolder=`pwd`
-
-if [ -e ./$(projectFolder) ]; then
-
-    # Install jazzy
-    sudo gem install jazzy
-    # Generate xcode project
-    sourceScript "${projectFolder}/generate-xcodeproj.sh"
-    # Run jazzy
-    jazzy
-
-    # Configure endpoint
-    REPO=`git config remote.origin.url`
-    AUTH_REPO=${REPO/https:\/\/github.com\//https://${GITHUB_USERNAME}:${GITHUB_PASSWORD}@github.com/}
-
-    git add docs/.
-    git commit -m 'Documentation update [ci skip]'
-    git push
+# Check that projectFolder and SCRIPT_DIR exist. These should have been set
+# by the calling script (build-package.sh)
+if [ -z "${projectFolder}" ]; then
+    projectFolder="$pwd"
+    echo "Warning: projectFolder not set. Defaulting to pwd ($projectFolder)"
 fi
+
+if [ -z "${SCRIPT_DIR}" ]; then
+    # Determine location of this script
+    SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
+    echo "Warning: SCRIPT_DIR not set. Defaulting to current script location ($SCRIPT_DIR}"
+fi
+
+# Check if .jazzy.yaml exists in the root folder of the repo. If we do not find
+# it, fail the build because the build explicitly requested docs generation.
+if [ ! -f "${projectFolder}/.jazzy.yaml" ]; then
+    echo ".jazzy.yaml file does not exist"
+    exit 1
+fi
+
+# Checkout to the current branch. The repo cloned by Travis is a shallow clone,
+# so we cannot check out the branch directly. Instead, create a new remote for
+# this purpose and checkout the branch from there.
+git remote add jazzy https://${GITHUB_USERNAME}:${GITHUB_PASSWORD}@github.com/${TRAVIS_REPO_SLUG}.git
+git fetch jazzy
+git checkout jazzy/${TRAVIS_PULL_REQUEST_BRANCH} -b ${TRAVIS_PULL_REQUEST_BRANCH}
+
+# Install jazzy
+sudo gem install jazzy
+# Generate xcode project
+sourceScript "${SCRIPT_DIR}/generate-xcodeproj.sh" "xcodeproj generation"
+# Run jazzy
+jazzy
+
+# Configure user
+git config --global --add user.name Auto-Jazzy
+git config --global --add user.email ${GITHUB_EMAIL}
+git config --global --add push.default simple
+
+# Push the updated docs as a new commit to the PR branch
+git add docs/.
+git commit -m 'Documentation update [ci skip]'
+git push