README to .md; rationalized ties between README and instructions

[catherinedevlin]

Here's my attempt at smoothing out the relationship between README and instructions.md, mostly by moving "detail sections" to instructions.md and tripping README down to the quickstarts.

[jmcarp]

What's the motivation for switching from rst? In my experience, it's the de facto standard for python docs, mostly because it's what sphinx uses: http://docs.python-guide.org/en/latest/writing/documentation/#restructuredtext.

[catherinedevlin]

@jmcarp true, but I was trying to adhere what seems to be an ad-hoc 18F standard:

Catherines-MBP:18F catherine$ find . -name "README.rst" | wc -l
      13
Catherines-MBP:18F catherine$ find . -name "README.md" | wc -l
    2098

[jmcarp]

I'm not sure what to make of those counts, since most 18f repos aren't python libraries (I don't have an opinion about docs formatting for applications). Anyway, especially for library code that we want to be reusable in the wider community, I think that community standards matter more than unwritten 18f standards.

Obviously not a big deal, and I don't mean to be pedantic--just posting my unsolicited $0.02.

[toolness]

Hmm, good point about reusable libraries... I guess I am OK with either rst or md, but I'd really prefer that all our docs use a consistent format, so that it's e.g. easy to move content from one file to another and so forth. Since @catherinedevlin has already done the work to convert RST to MD, I propose we just go with MD for now, but I'm open to other suggestions!

[toolness]

I'm not sure what to make of those counts, since most 18f repos aren't python libraries (I don't have an opinion about docs formatting for applications). Anyway, especially for library code that we want to be reusable in the wider community, I think that community standards matter more than unwritten 18f standards.

Er, for that matter, is autoapi considered library code, or application code? I had assumed it was application code, especially since we're starting to get very opinionated about how it's deployed and what it supports--in which case the doc format shouldn't matter much. I could be mistaken though.

[vrajmohan]

In general terms, I would view this as an application rather than a library as a basis for making decisions. We can always change it later. With that said, as we are building open source applications that we would like others outside 18F to contribute/fork/whatever, I would stick with language standards rather than unwritten 18F standards. In short, my opinion is to keep it rst.