Make docs incorporate READMEs

[matt-gardner]

We have a few places under doc/ where we've written explanations of things. Those explanations really should be in READMEs in the code, and just read from the README and put into doc/, instead of duplicated in both places.

I don't know if this is easy or hard, because I don't know enough about how sphinx works, or how ReadTheDocs actually builds our docs for each commit. It's probably hard.

[nelson-liu]

This is probably not too hard. Here's an example of how scikit-learn does it:

• There's an about.rst in the doc/ directory
  • If you look at the raw source of that rst, note the .. include:: ../AUTHORS.rst. This basically tells sphinx "ok, go to that path, take all the stuff in that RST file and put it in here"
• Then, the final generated doc looks like this. Note that the contents of AUTHORS.rst have been inserted

[matt-gardner]

Nice, thanks Nelson! It probably means that we'd need to move to RST instead of markdown everywhere, though... I was hoping to go the other way, but I could live with it if it gives us nicer docs.

[matt-gardner]

There might be a way to combine the two: https://github.com/sphinx-doc/sphinx/issues/2840#issuecomment-284863143.