Travis: apidoc: script, compare view, PR comment
This moves the apidoc uploading to build-utils/travis-apidoc.sh, which makes it more pleasant to maintain/read. Additional enhancements: - handle all branches and PRs, and provide compare view links as a comment for the latter, via awesome-robot. This gets skipped for PRs for forks, because then the Github secret is not available for security reasons. - use a merge commit to keep relevant changes and boilerplate together. - simplified/shorter AWESOME_VERSION override. - add last commit message of the repo to the apidoc's commit message. Closes https://github.com/awesomeWM/awesome/pull/358.
This commit is contained in:
Daniel Hahler
parent
ecddee44cb
commit
88ba798ae3
17
.travis.yml
17
.travis.yml
|
|
@ -95,22 +95,13 @@ install:
|
|||
- sudo apt-get install -qq dbus-x11 xterm xdotool xterm xvfb
|
||||
|
||||
# Determine custom version.
|
||||
- '[ "$TRAVIS_PULL_REQUEST" = false ] && AWESOME_VERSION="${TRAVIS_BRANCH}-g$(git rev-parse --short HEAD)-$(date -Iseconds)" || AWESOME_VERSION="${TRAVIS_BRANCH}-PR${TRAVIS_PULL_REQUEST}-g$(git rev-parse --short HEAD)-$(date -Iseconds)"'
|
||||
- export AWESOME_VERSION="${TRAVIS_BRANCH}-g$(git rev-parse --short HEAD)"
|
||||
- 'if [ "$TRAVIS_PULL_REQUEST" != false ]; then AWESOME_VERSION="${AWESOME_VERSION}-PR${TRAVIS_PULL_REQUEST}"; fi'
|
||||
|
||||
script:
|
||||
- export CMAKE_ARGS="-DLUA_LIBRARY=${LUALIB} -DLUA_INCLUDE_DIR=/usr/include/lua${LUAPKG} -D OVERRIDE_VERSION=$AWESOME_VERSION"
|
||||
- make && sudo env PATH=$PATH make install && awesome --version && tests/run.sh
|
||||
|
||||
# Push updated API docs for non-PRs builds on master.
|
||||
# It uses "diff -I .." to check if there are relevant changes, and then adds
|
||||
# them in two separate commits. This allows to more easily see real changes to
|
||||
# the documentation.
|
||||
after_success:
|
||||
- REPO_APIDOC="https://${GH_TOKEN}@github.com/awesomeWM/apidoc"
|
||||
# Export these to not add "git config" calls to the long command.
|
||||
- export GIT_AUTHOR_NAME="awesome-robot on Travis CI"
|
||||
- export GIT_AUTHOR_EMAIL="awesome-robot@users.noreply.github.com"
|
||||
- export GIT_COMMITTER_NAME="$GIT_AUTHOR_NAME"
|
||||
- export GIT_COMMITTER_EMAIL="$GIT_AUTHOR_EMAIL"
|
||||
# NOTE: stdout/stderr might/should be discarded to not leak sensitive information.
|
||||
- '[ "BUILD_APIDOC" = "true" ] && [ "$TRAVIS_BRANCH" = "master" ] && [ "$TRAVIS_PULL_REQUEST" = false ] && { echo "Uploading documentation..." && cd build && git clone --quiet --branch gh-pages $REPO_APIDOC apidoc && diff -Nur apidoc doc -I "Last updated" -I "<strong>Release</strong>:" -I "(version master-" -x .git > /tmp/p1; { echo "Patch:"; cat /tmp/p1; } && cd apidoc && patch -p1 < /tmp/p1 && git add --all . && git commit -m "Update docs for $AWESOME_VERSION via Travis" && { mv .git ../doc && cd ../doc && git add --all . && git commit -m "minor: update timestamps/version" && git push --quiet origin gh-pages || echo "Uploading docs failed!"; } || echo "Documentation has not changed."; } || echo "Not uploading docs for $TRAVIS_BRANCH:$TRAVIS_PULL_REQUEST."'
|
||||
# Push updated API docs for relevant branches, e.g. non-PRs builds on master.
|
||||
- if [ "BUILD_APIDOC" = "true" ]; then build-utils/travis-apidoc.sh; fi
|
||||
|
|
|
|||
|
|
@ -0,0 +1,102 @@
|
|||
#!/bin/sh
|
||||
#
|
||||
# Process (API) docs after a successful build on Travis (via ../.travis.yml).
|
||||
#
|
||||
# Updated/changed documentation for "master" is pushed to gh-pages.
|
||||
# In case of pull requests or other branches, it will get added to a separate branch.
|
||||
# In case of a pull request, a compare view comment will be posted.
|
||||
#
|
||||
# NOTE: stdout/stderr might/should be discarded to not leak sensitive information.
|
||||
|
||||
echo "Post-processing (API) documentation."
|
||||
echo "TRAVIS_PULL_REQUEST: $TRAVIS_PULL_REQUEST"
|
||||
echo "TRAVIS_BRANCH: $TRAVIS_BRANCH"
|
||||
|
||||
# GH_TOKEN won't be available for PRs from forks.
|
||||
# (http://docs.travis-ci.com/user/pull-requests/#Security-Restrictions-when-testing-Pull-Requests).
|
||||
if [ -z "GH_TOKEN" ]; then
|
||||
echo "No GH_TOKEN available. Skipping."
|
||||
exit
|
||||
fi
|
||||
|
||||
# NOTE: DO NOT USE "set -x", or anything else that would reveal GH_TOKEN!
|
||||
set -e
|
||||
set +x
|
||||
|
||||
REPO_APIDOC="https://${GH_TOKEN}@github.com/awesomeWM/apidoc"
|
||||
REPO_DIR="$PWD"
|
||||
|
||||
# Export these to not add "git config" calls to the long command.
|
||||
export GIT_AUTHOR_NAME="awesome-robot on Travis CI"
|
||||
export GIT_AUTHOR_EMAIL="awesome-robot@users.noreply.github.com"
|
||||
export GIT_COMMITTER_NAME="$GIT_AUTHOR_NAME"
|
||||
export GIT_COMMITTER_EMAIL="$GIT_AUTHOR_EMAIL"
|
||||
|
||||
git clone --quiet --branch gh-pages $REPO_APIDOC build/apidoc
|
||||
cd build/apidoc
|
||||
|
||||
# This will re-use already existing branches (updated PR).
|
||||
if [ "$TRAVIS_PULL_REQUEST" != false ]; then
|
||||
BRANCH="pr-$TRAVIS_PULL_REQUEST"
|
||||
elif [ "$TRAVIS_BRANCH" != master ]; then
|
||||
# Use merge-base of master in branch name, to keep different branches with
|
||||
# the same name apart.
|
||||
BRANCH=$TRAVIS_BRANCH-$(cd ${REPO_DIR} \
|
||||
&& git fetch --unshallow origin master \
|
||||
&& git rev-parse --short $(git merge-base HEAD FETCH_HEAD || true) || true)
|
||||
else
|
||||
BRANCH="gh-pages"
|
||||
fi
|
||||
if [ "$BRANCH" != "gh-pages" ]; then
|
||||
git checkout -b "$BRANCH" "origin/${BRANCH}" || git checkout -b "$BRANCH"
|
||||
fi
|
||||
|
||||
# Use a temporary branch for the two commits, which allows for a better UI.
|
||||
git checkout -b merged-update
|
||||
|
||||
# Create a patch without irrelevant changes (version / timestamp).
|
||||
diff -Nur . ../doc -I "Last updated" -I "<strong>Release</strong>:" \
|
||||
-I "<h2>API documentation for awesome, a highly configurable X window manager \(version .*\)\.</h2>" \
|
||||
-x .git | patch -p1
|
||||
|
||||
git add --all .
|
||||
if git diff --cached --exit-code --quiet; then
|
||||
echo "Documentation has not changed."
|
||||
exit
|
||||
fi
|
||||
|
||||
# Commit the relevant changes.
|
||||
OLD_REV="$(git rev-parse --short HEAD)"
|
||||
COMMIT_MSG="Update docs for $AWESOME_VERSION via Travis
|
||||
|
||||
Last commit message:
|
||||
$(cd $REPO_DIR && git log -1 --pretty=format:%s)
|
||||
|
||||
Build URL: https://travis-ci.org/awesomeWM/awesome/builds/${TRAVIS_BUILD_ID}"
|
||||
git commit -m "[relevant] $COMMIT_MSG"
|
||||
NEW_REV="$(git rev-parse --short HEAD)"
|
||||
|
||||
# Commit the irrelevant changes.
|
||||
mv .git ../doc
|
||||
cd ../doc
|
||||
git add --all .
|
||||
git commit -m "[boilerplate] $COMMIT_MSG"
|
||||
|
||||
git checkout "$BRANCH"
|
||||
git merge --no-ff -m "$COMMIT_MSG" merged-update
|
||||
|
||||
git push --quiet origin "$BRANCH"
|
||||
|
||||
# Generate compare view links.
|
||||
COMPARE_LINKS="Compare view: https://github.com/awesomeWM/apidoc/compare/${OLD_REV}...${NEW_REV}"
|
||||
if [ "$BRANCH" != "gh-pages" ]; then
|
||||
COMPARE_LINKS="$COMPARE_LINKS\nComparison against master (gh-pages): https://github.com/awesomeWM/apidoc/compare/gh-pages...${NEW_REV}"
|
||||
fi
|
||||
echo "Compare links:\n$COMPARE_LINKS"
|
||||
|
||||
# Post a comment to the PR.
|
||||
if [ "$TRAVIS_PULL_REQUEST" != false ]; then
|
||||
curl -H "Authorization: token $GH_TOKEN" \
|
||||
-d "{\"body\": \"Documentation has been updated for this PR:\n$COMPARE_LINKS\"}" \
|
||||
https://api.github.com/repos/awesomeWM/awesome/issues/${TRAVIS_PULL_REQUEST}/comments
|
||||
fi
|
||||
Loading…
Reference in New Issue