Generate index.html only on gh-pages when deploying

- Build index.html at deploy time
- Update corresponding documentation references
- Since index.html is untracked, git add needs -f
- Clarify gh-pages generated commit message
- Improve Makefile dependencies related to website generation

As discussed in #936, tracking the index.html causes makes PRs longer / noisier
and causes extra merge conflicts. More importantly, it causes contributors to
inadvertently edit the wrong file, which causes extra work (#949) or
contributions to be lost (#898).

Since there's no need for index.html in development (everything uses try.html) a
logical solution is to generate and commit the index.html at deploy time.

Recording compiled or generated files in a deploy commit is a reasonable
practice for git-based deploys (Heroku, gh-pages, and others).

The old version of this was slightly "unsafe" for my taste, in that it depended
on the local copy of gh-pages (if it existed) and master. The new version just
replaces gh-pages with master + the new commit.

Closes #936.

Fixes #954 (the PR).

.gitignore

@@ -5,6 +5,7 @@
 /redis
 /ServerScript
 /private
+/index.html
 
 # Folder view configuration files
 .DS_Store

CONTRIBUTING.md

@@ -14,8 +14,6 @@ You can read a [Tutorial on how to add a badge](doc/TUTORIAL.md).
 
 Note that the root gets redirected to <http://shields.io>.
 For testing purposes, you can go to `http://localhost/try.html`.
-You should modify that file. The "real" root, `http://localhost/index.html`,
-gets generated from the `try.html` file with a `make website`.
 
 ## Ground rules
 

INSTALL.md

@@ -66,8 +66,6 @@ node server 8080
 
 The root gets redirected to <http://shields.io>.
 For testing purposes, you can go to `http://localhost/try.html`.
-You should modify that file. The "real" root, `http://localhost/index.html`,
-gets generated from the `try.html` file.
 
 # Format
 
@@ -157,6 +155,14 @@ http://[::1]:80/try.html
 
 Assuming Docker is running locally, you should be able to get to the application at http://localhost:8080/try.html. If you run Docker in a virtual machine (such as boot2docker or Docker Machine) then you will need to replace `localhost` with the actual IP address of that virtual machine.
 
+# Build the index
+
+Build the "real" index page:
+
+```bash
+make website
+```
+
 # Secret.json
 
 Some services require the use of secret tokens or passwords. Those are stored in `private/secret.json` which is not checked into the repository, to avoid impersonation. Here is how it currently looks like:

Makefile

@@ -46,9 +46,10 @@ deploy-s2:
 	git reset HEAD~1
 	git checkout master
 
-deploy-gh-pages:
-	(git checkout -B gh-pages && \
-	git merge master && \
+deploy-gh-pages: website
+	(git checkout -B gh-pages master && \
+	git add -f index.html && \
+	git commit -m '[DEPLOY] Build index.html' && \
 	git push -f origin gh-pages:gh-pages) || git checkout master
 	git checkout master
 

doc/TUTORIAL.md

@@ -217,12 +217,6 @@ Edit [try.html][tryhtml] in the right section (Build, Downloads, ...) and add yo
 
 Save, restart and you can see it [locally][try].
 
-If this is fine, you can generate the website:
-
-    make website
-
-This changes the index.html file automatically.
-
 ## (5) Create a Pull Request
 
 You have implemented changes in `server.js`, `try.html` and `index.html`.