Back-merge documentation updates from master

Draft development guidelines, link from README
minor readme polish
add hardware notes to installation
outline pull request etiquette
polish doc build and deploy and allow other remotes
fix path for mnist leveldb creation
fix examples shell scripts: too many dollar signs, not enough coffee
fix formatting + notebook url of 8c245b5
update detection example post re-arrangement in #124

1 files changed, 24 insertions, 13 deletions

diff --git a/scripts/build_and_deploy_docs.sh b/scripts/build_and_deploy_docs.sh
index 83b79b26..85121b6e 100755
--- a/scripts/build_and_deploy_docs.sh
+++ b/scripts/build_and_deploy_docs.sh
@@ -1,37 +1,48 @@
-echo "The remote from which you will submit the PR to BVLC:gh-pages must be called 'origin'"
+#!/usr/bin/env sh
+# Publish/ Pull-request documentation to the gh-pages site.
+
+# The remote for pushing the docs (defaults to origin).
+# This is where you will submit the PR to BVLC:gh-pages from.
+REMOTE=${1:-origin}
+
+echo "Generating docs and pushing to $REMOTE:gh-pages..."
 echo "To build and view docs when not on master, simply do 'jekyll serve -s docs'."
 echo
 
-ORIGIN=`git config --get remote.origin.url`
+REMOTE_URL=`git config --get remote.${REMOTE}.url`
 BRANCH=`git rev-parse --abbrev-ref HEAD`
 MSG=`git log --oneline -1`
 
-if [ $BRANCH = 'master' ]; then
+if [[ $BRANCH = 'master' ]]; then
+    # Find the docs dir, no matter where the script is called
+    DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
+    DOCS_SITE_DIR=$DIR/../docs/_site
+
     # Make sure that docs/_site tracks remote:gh-pages.
     # If not, then we make a new repo and check out just that branch.
-    mkdir docs/_site
-    cd docs/_site
-    SITE_ORIGIN=`git config --get remote.origin.url`
+    mkdir -p $DOCS_SITE_DIR
+    cd $DOCS_SITE_DIR
+    SITE_REMOTE_URL=`git config --get remote.${REMOTE}.url`
     SITE_BRANCH=`git rev-parse --abbrev-ref HEAD`
 
-    echo $SITE_ORIGIN
+    echo $SITE_REMOTE_URL
     echo $SITE_BRANCH
     echo `pwd`
 
-    if [[ ( $SITE_ORIGIN == $ORIGIN ) && ( $SITE_BRANCH = 'gh-pages' ) ]]; then
-        echo "Confirmed that docs/_site has same origin as main repo, and is on gh-pages."
+    if [[ ( $SITE_REMOTE_URL = $REMOTE_URL ) && ( $SITE_BRANCH = 'gh-pages' ) ]]; then
+        echo "Confirmed that docs/_site has same remote as main repo, and is on gh-pages."
     else
-        echo "Checking out origin:gh-pages into docs/_site (will take a little time)."
+        echo "Checking out $REMOTE:gh-pages into docs/_site (will take a little time)."
         git init .
-        git remote add -t gh-pages -f origin $ORIGIN
-        git co gh-pages
+        git remote add -t gh-pages -f $REMOTE $REMOTE_URL
+        git checkout gh-pages
     fi
 
     echo "Building the site into docs/_site, and committing the changes."
     jekyll build -s .. -d .
     git add --all .
     git commit -m "$MSG"
-    git push origin gh-pages
+    git push $REMOTE gh-pages
 
     echo "All done!"
     cd ../..