convert and move about 1/2 of our docs from .rst to .md

This change starts converting our docs from sphinx-powered-rst to Pants-enhanced-md, moving files to some different directories:

src/docs/*.md  <= language-agnostic Pants-user docs

examples/src/java/com/pants/examples/*.md  <= Pants-with-Java docs

examples/src/python/example/*.md  <= Pants-with-py docs

src/python/pants/docs  <= good place for pants-dev docs

Keeping foolang docs with examples/src/foolang feels right; if we change the examples, we probably want to change the docs, too. Less-certain about where language-agnostic docs go.

Testing Done:
eyeball-compare pages gen'd from .rst, .md

Reviewed at https://rbcommons.com/s/twitter/r/1176/
'goal sitegen' tweaks inspired by eyeballing more Pants doc pages

Don't insert pilcrow anchor in the heading; instead, lay it nearby with a table. Otherwise, it looks funny if the line breaks right there.

Add a "Generated by publish_docs dist/markdown/html/README.html 2014-10-17T11\:16:07.253750" so that folks who are looking at a doc from two years ago have an inkling of the danger. And/or if they want to fix a mistake, they have a clue where the content came from.

Widened margin around the page-level table of contents.

Testing Done:
https://travis-ci.org/pantsbuild/pants/builds/38290410

Reviewed at https://rbcommons.com/s/twitter/r/1178/