[Docs] Build and update documentation automatically from Travis CI

.gitignore

@@ -62,4 +62,5 @@ fastlane/screenshots
 Carthage
 
 # Generated documentation
-Docs/tmp
+Docs/tmp
+Docs/output

.jazzy.json

@@ -1,16 +1,14 @@
 {
     "xcodebuild_arguments": ["-project", "ReSwift.xcodeproj", "-scheme", "ReSwift-macOS"],
-    "swift_version": "2.1.1",
-    "author_name": "ReSwift",
+    "swift_version": "2.2",
+    "author": "ReSwift",
     "author_url": "https://github.com/ReSwift/ReSwift",
-    "module_name": "ReSwift",
-    "readme_path": "Docs/tmp/compile/README.md",
-    "docset_platform": "reswift",
-    "assets_directory": "Docs/jazzy-theme/assets",
-    "template_directory": "Docs/jazzy-theme/templates",
+    "module": "ReSwift",
+    "readme": "Docs/tmp/compile/README.md",
+    "theme": "Docs/jazzy-theme/",
 
-    "documentation_glob": "Docs/tmp/docs/*.md",
-    "abstract_glob": "Docs/tmp/api/*.md",
+    "documentation": "Docs/tmp/docs/*.md",
+    "abstract": "Docs/tmp/api/*.md",
 
     "custom_categories": [{
         "name": "Documentation",

.scripts/generate-docs

@@ -0,0 +1,84 @@
+#!/bin/bash
+
+# ----- Check for dependencies
+
+JAZZY=$(which jazzy)
+if [ $? != 0 ]; then
+    echo -e "Jazzy is required to generate documentation. Install it with:\n"
+    echo -e "    gem install jazzy\n"
+    exit
+fi
+echo "Using jazzy: $JAZZY"
+
+
+# ----- Commandline options
+
+if [ "$BRANCH" == "" ]; then
+  BRANCH=$([ "$1" == "" ] && echo "master" || echo "$1")
+fi
+
+if [ "$OUTPUT_PATH" == "" ]; then
+  OUTPUT_PATH=$([ "$2" == "" ] && echo "Docs/output/$BRANCH" || echo "$2")
+fi
+
+
+# ----- Configuration
+
+ORGANISATION=ReSwift
+NAME=ReSwift
+TMP=Docs/tmp
+GITHUB=https://github.com/$ORGANISATION/$NAME
+URL=http://$ORGANISATION.github.io/$NAME
+
+PREPROC=.scripts/doc-preprocessor
+
+# ----- Setup and generate docs
+
+# Clean $TMP folder
+if [ -d "$TMP" ]; then rm -rf "$TMP"; fi
+mkdir -p $TMP/{compile,docs,api}
+
+cp Docs/*.md $TMP/api/
+
+# Split the README into sections
+$PREPROC README.md "$TMP/docs/About ReSwift.md" --section "About ReSwift" --title "About ReSwift"
+$PREPROC README.md "$TMP/docs/Why ReSwift.md" --section "Why ReSwift?" --title "Why ReSwift?"
+$PREPROC README.md "$TMP/docs/Installation.md" --section "Installation" --title "Installation"
+$PREPROC README.md "$TMP/docs/Checking out Source Code.md" --section "Checking out Source Code" --title "Checking out Source Code"
+$PREPROC README.md "$TMP/docs/Demo.md" --section "Demo" --title "Demo"
+$PREPROC README.md "$TMP/docs/Extensions.md" --section "Extensions" --title "Extensions"
+$PREPROC README.md "$TMP/docs/Example Projects.md" --section "Example Projects" --title "Example Projects"
+$PREPROC README.md "$TMP/docs/Credits.md" --section "Credits" --title "Credits"
+$PREPROC README.md "$TMP/docs/Get in touch.md" --section "Get in touch" --title "Get in touch"
+$PREPROC README.md "$TMP/compile/intro.md" --section "Introduction"
+
+# Copy remaining root docs
+$PREPROC CONTRIBUTING.md "$TMP/docs/Contributing.md"
+$PREPROC CHANGELOG.md "$TMP/docs/Changelog.md" --title "Changelog"
+$PREPROC LICENSE.md "$TMP/docs/License.md" --title "License"
+
+# Copy over the Getting started guide
+$PREPROC "Docs/Getting Started Guide.md" "$TMP/docs/Getting Started Guide.md"
+
+# Create the documentation landing page by combining:
+#
+# - Docs/templates/heading.md
+# - README.md#introduction
+# - Docs/templates/toc.md
+#
+cat Docs/templates/heading.md $TMP/compile/intro.md Docs/templates/toc.md > $TMP/compile/readme-raw.md
+$PREPROC "$TMP/compile/readme-raw.md" "$TMP/compile/README.md"
+cp $TMP/compile/README.md $TMP/api/Documentation.md
+
+# Compile our Docs/tmp + generate API docs using jazzy
+jazzy \
+  --config .jazzy.json \
+  --clean \
+  --output "$OUTPUT_PATH" \
+  --module-version "$BRANCH" \
+  --dash_url "$URL/$BRANCH/docsets/$NAME.xml" \
+  --root-url "$URL/$BRANCH/" \
+  --github_url "$GITHUB" \
+  --github-file-prefix "$GITHUB/tree/$BRANCH"
+
+cp Docs/img/* $OUTPUT_PATH/img/

.scripts/update-gh-pages

@@ -0,0 +1,82 @@
+#!/bin/bash
+
+# ----- Early exit check
+
+if [ "$TRAVIS_BRANCH" != "" ]; then
+    # Exit if we are running inside travis but not on the iOS scheme
+    if [ "$SCHEME" != "iOS" ]; then
+        echo " <== Early exit - SCHEME='$SCHEME'"
+        exit 0
+    fi
+fi
+
+
+# ----- Configuration
+
+ORGANISATION=ReSwift
+NAME=ReSwift
+BRANCH=$([ "$TRAVIS_BRANCH" == "" ] && echo "master" || echo "$TRAVIS_BRANCH")
+SHA=`git rev-parse --verify HEAD --short`
+REPO=`git config remote.origin.url`
+
+TMP=Docs/tmp
+CHECKOUT_PATH=Docs/output
+OUTPUT_PATH=$CHECKOUT_PATH/$BRANCH
+
+
+# ----- Clone the GitHub pages repo if required
+
+echo " ==> Updating documentation for '$BRANCH' branch"
+
+if [ -d "$CHECKOUT_PATH" ]; then
+    echo " ==> Update: gh-pages -> $CHECKOUT_PATH"
+    git -C "$CHECKOUT_PATH" pull origin gh-pages
+else
+    echo " ==> Checkout: gh-pages -> $CHECKOUT_PATH"
+    git clone --branch gh-pages "$REPO" "$CHECKOUT_PATH"
+fi
+
+if [ "$TRAVIS_BRANCH" != "" ]; then
+    echo " ==> Install: jazzy"
+    gem install --no-rdoc --no-ri jazzy
+fi
+
+echo " ==> Generate documentation"
+.scripts/generate-docs "$BRANCH" "$OUTPUT_PATH"
+
+# ----- Travis Documentation updater
+
+# Exit if not running from travis
+if [ "$TRAVIS_BRANCH" == "" ]; then exit; fi
+if [ "$SCHEME" != "iOS" ]; then exit; fi
+
+pushd "$CHECKOUT_PATH"
+
+    git config user.name "Travis CI"
+    git config user.email "$COMMIT_AUTHOR_EMAIL"
+
+    # Exit if there are no changes to the documentation
+    echo " ==> Check for documentation changes"
+    CHANGE_SET=$(git status -s)
+    if [ "$CHANGE_SET" == "" ]; then
+        echo " <== No changes to the output on this push; exiting."
+        exit 0
+    fi
+
+    # Exit if only the docset archive has changed (it always changes)
+    if [ "$CHANGE_SET" == " M $BRANCH/docsets/$NAME.tgz" ]; then
+        echo " <== Only the docset archive changed on this push; exiting."
+        exit 0
+    fi
+
+    echo " ==> Stage changes"
+    git add -A "$BRANCH"
+
+    echo " ==> Commit changes"
+    git commit -m "[$BRANCH $SHA] Regenerate documentation"
+
+    echo " ==> Push changes -> '$REPO'"
+    git push -q "https://$GITHUB_PAGES_TOKEN@github.com/$ORGANISATION/$NAME.git" gh-pages
+
+    echo " <== All done 👊"
+popd

.travis.yml

@@ -44,6 +44,7 @@ script:
 
 after_success:
   - bash <(curl -s https://codecov.io/bash) -J ReSwift
+  - test $TRAVIS_PULL_REQUEST == "false" && test $TRAVIS_BRANCH == "master" && .scripts/update-gh-pages
 
 before_deploy:
   - carthage build --no-skip-current