.rst files -> .md files.

re-play https://rbcommons.com/s/twitter/r/1235/ , "convert more .rst files to .md", but less crash-y. Also pull in some excellent feedback and update with doc changes that went into the .rst.

The crashy change converted many rst docs to Pants-enhanced markdown (yay) with BUILD targets (yay) with circular deps which 'goal markdown' is OK with (hmm) but which 'goal test' balks at, breaking CI (d'oh). So I reverted that change.

*This* change is like *that* change, but

* Uses the new `links` BUILD param instead of `dependencies`. Yay for no CI breaks.
* Pulls in an additition the excellent AReitz made to JVMProjects.rst meanwhile.
* Includes feedback from same excellent AReitz.
* pulls in .rst changes that came in at https://rbcommons.com/s/twitter/r/1279/

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

http://pantsbuild.github.io/sitegen-test/

Reviewed at https://rbcommons.com/s/twitter/r/1263/
Sync of https://github.com/pantsbuild/pants/commit/36ee394296de372f7b13ee5109a2def0003567e3