This is a user manual for an example project.

Introduction

This project generates HTML documentation with Asciidoc.

Publish to Github Pages

The documentation is published to Github Pages using travis-build.sh.

travis.yml
sudo: required
cache:
  directories:
  - "$HOME/.gradle"
dist: trusty
addons:
  chrome: stable
jdk:
- oraclejdk8
before_script:
- rm -rf target
script: "./travis-build.sh"
env:
  global:
  - secure: VUwR4Jtq+304aDDoLG87gF9K0HGjmjI3pHlELDErGx63W99DHWPADOWRKxmlS6zSX0/QzZw/KYQmOnBcP8COfoY2UNR73BBGUquaM8lqol/1NnMlpmZd0G1Mtw4TS59DCsNg3gG0fS4BMxFBxLe/3Yu7suRnrhB6OusNoOQ2KtYqYj4uwXmCnFdCG83emzOZ5HAyJGgog0cMqvWrCe0qZncQ8SHsZWt21Uc0o0Q+rsf1uKWFPLk48m061r3FObBt2p2RG4NIz3GVDcsoH6IAzl1DL2fAwehdkXcPApz7adda+wESJ4xmCVTXWLkkrzNjdb1i4xwYGmAlgGjCdl6WqK1bcdhPF7Bnv8xsp7xtWQS/cMiu6aYuPmyGgl6W9Egy58QLZXSdVZqlL8952d4Ktt1b36TG/e0ddvrXscZRPDXDlj8SGWzO/loPXoxzvKlbvP3Y43SyzCxdBBVsx0ySeaIDUdaDfl8MIoG1zqstVPHi11/UHZiaOcKVYJ1zLF+wDq3ElqacgcbcPfxUIswnfMLzyVPEAjyOZX4tZih7bd3cIZLZOm1UMTZm+LvJKo7PwrJkAcRVoUgwD24ehVEpFNdIYvnx9JG8t57Z2LRCmvHdHQcFYzYuH2IfGFFKOrLxZfXHh33Yo5YKH4K7Ier/EpxGxtYvAtm7R5BYunE2+EI=
  - secure: qKpjVbyGGB6yG3jXaero1PvOra1HB2GzWNvKr3cOX+tXtDVZ3WzsxnKBqMYHCCYdzL6Qx7Vjqt3CUcGy33ePikosAZb+BY+JIUrV8dUCUjqpL0HtH7OAbeOpPpEOwAiThN+feJ7u+8MhlVxBaeZ/0MqwGf6k9mEW+WfGfY95TuNcp67hZhSujIft+x9bhcf/a8W6qtXK9ojSfdvX3/y2n1WAb5rpxdVqS/BcQKcd9kvrYx0/ebkPmxTv/os7yRYjum0tGuPUvS5PYPHvIdD2RvoLUUy/72qg/4oLoM9BcnQH0VR7EcOaHN1YhtWuaCab4xZSYTRSm1HY4Cdg12901azI2is0BY4jQt19lihsyB86p6rfpzWPm0RDMUMX3Xp+6fx8bh85FGsX0InAOB/OcyFoGGU2c5k96wmO4qnr2DP/d82r1mElR6degQIiWt+LUMwDpz0W7ZWGDhpHQA+mrE14XBsRvg7zhenyc7c6otPNQpa1xgLDhpH+yHvMu1yor/Q74tWVto2u9nFIpWJYatFMSPHLsMJSukya1UrTS++ozTaU8qOEgw7kJFzaI5ESWanl0+ajbfkQ5zoDV0dT4GiOdWeqqUtbFP4FaKFxXF/KZefw7/czyCFXIelMILMb8h+eKFpSaa3jQOhnAAA2mQF+nj+NIGXLtqgNE9IAVzk=
  - secure: jwt/X6uc7VdR4pw91ORVWHrO5vIPUNnHISWC0I5xTc3MXE1/unNMwN9LOqve61bOghS+ms+ROUFJRLRFeMtbz2JaD/cZBsPb4vHMgmgfnXs0KskDqYVHMUclp8UzTkThopfZVnY8WKZATG/e8fy1N7qNtadf6bN+dywDG1pwuyegv6VAIv6F6GHxMppfPKFp0kEqyOWgniONa1MpDdDV5Z9cs4npHrhMM2fVZuXYrPL8YellgfQivzlgzZDE6lKIqToVZprGjcqN8HdC0qXgI76WVCAMesOPoXZLFV0SBXiwQaBEFJca48dexL9W9sFBREfvHMOC59Vln+Z/QB1PhUKbx58geve87G221V6SUs5jxNtiWn8kWvuIgPhJ0Cj3ncS6EEat40l0jMxwSIgFteflQ+ihBhGx1jo0Ck3aS9KqgwzOLDGpLt5dkNbWJIcOeJV6BX8r1lnek3yEoNbZzpTp5JMlHErLq8XdzcJr1gADn6YOXHcN0vle8XnXbXm9WQ+YUrirML00kzFTfdjRetYNqFHbNqCAYUkvVuf3kVAEQF8f0GVnEIXmZS3GGReae7lN0w5VDjmxfpuFwRMY2w4bHGvmqxfexu+dvNLbvxz3h6TRRDWyHLs8alqkjTB9InHq1Ks9cwo95/dC5vwI4F5tKQhieR6ZaJGEicCdd9k=
travis-build.sh
#!/bin/bash
set -e

EXIT_STATUS=0

./gradlew clean || EXIT_STATUS=$?

if [[ $EXIT_STATUS -ne 0 ]]; then
    echo "Clean failed"
    exit $EXIT_STATUS
fi

./gradlew check || EXIT_STATUS=$?

if [[ $EXIT_STATUS -ne 0 ]]; then
    echo "Check failed"
    exit $EXIT_STATUS
fi

# Only publish docs if the branch is on master, and it is not a PR
if [[ -n $TRAVIS_TAG ]] || [[ $TRAVIS_BRANCH == 'master' && $TRAVIS_PULL_REQUEST == 'false' ]]; then

  ./gradlew docs || EXIT_STATUS=$?

  if [[ $EXIT_STATUS -ne 0 ]]; then
    echo "Docs generation failed"
    exit $EXIT_STATUS
  fi

  git config --global user.name "$GIT_NAME"
  git config --global user.email "$GIT_EMAIL"
  git config --global credential.helper "store --file=~/.git-credentials"
  echo "https://$GH_TOKEN:@github.com" > ~/.git-credentials

  git clone https://${GH_TOKEN}@github.com/${TRAVIS_REPO_SLUG}.git -b gh-pages gh-pages --single-branch > /dev/null
  cd gh-pages

  # If this is the master branch then update the snapshot
  if [[ $TRAVIS_BRANCH == 'master' ]]; then
    mkdir -p snapshot
    cp -r ../build/asciidoc/html5/. ./snapshot/
    git add snapshot/*
  fi

  # If there is a tag present then this becomes the latest
  if [[ -n $TRAVIS_TAG ]]; then
    mkdir -p latest
    cp -r ../build/asciidoc/html5/. ./latest/
    git add latest/*

    version="$TRAVIS_TAG" # eg: v3.0.1
    version=${version:1} # 3.0.1
    majorVersion=${version:0:4} # 3.0.
    majorVersion="${majorVersion}x" # 3.0.x

    mkdir -p "$version"
    cp -r ../build/asciidoc/html5/. "./$version/"
    git add "$version/*"

    mkdir -p "$majorVersion"
    cp -r ../build/asciidoc/html5/. "./$majorVersion/"
    git add "$majorVersion/*"
  fi

  git commit -a -m "Updating docs for Travis build: https://travis-ci.org/$TRAVIS_REPO_SLUG/builds/$TRAVIS_BUILD_ID"
  git push origin HEAD
  cd ..
  rm -rf gh-pages

fi

exit $EXIT_STATUS