Moving gh-pages stuff to docs/ directory, with script to build and deploy to gh-pages.

[sergeyk]

This will allow easier documentation of code, as requested in #151.
The build script is kind of scary because uncommitted work in the code branch will be lost in the process of deployment. Not sure how to get around that -- right now we prompt people to understand what they're doing.

[shelhamer]

For further safety, we could add a failsafe check for a dirty tree:

if [ $(git status --porcelain 2> /dev/null | wc -l) != 0 ]; then
    # checkout is dirty, bail and warn
fi

More importantly, we need to not accidentally contaminate gh-pages by accidentally committing uncommitted work in the code branch (since it will be especially confusing on returning to master and finding your uncommitted changes gone).

[sergeyk]

I think I'll have a better solution in a few minutes

[sergeyk]

This solution is better. Try it out: scripts/build_and_deploy_docs.sh

[shelhamer]

The update is the right approach.

The requirement to work from master is good, because gh-pages should only track the stable master and published once changes are merged in.

One could go a step further, and makes docs/ a submodule to caffe:gh-pages but it is a step too far. While this would assure a checkout of caffe:master will always be up-to-date with the corresponding docs, it brings back the hassle of making separate commits and PRs for the project and its docs.

[sergeyk]

Sounds like a go-ahead to me!

[shelhamer]