The README was discussing future design decisions as if they were
already implemented. This can be confusing for new users. This
separates that discussion into a separate doc page and clarifies
its intentions.
Also, fix sphinx doc build warnings.
Change-Id: Ie66b60d972cae25a9805804ad17632aed0932627
0af29bda2f