add v3 API documentation

These are the restructuredtext documents produced as a result of the
following changes (originally proposed to openstack/identity-api):

* Convert markdown to restructured text:
  https://review.openstack.org/#/c/128676/

* Split HTTP methods & resources from section titles:
  https://review.openstack.org/#/c/128690/

* And a few minor content changes to comply with doc8:
  https://review.openstack.org/#/c/128693/

This change also adds doc8 validation to the new api/ directory.

Change-Id: Ia575cf8f00558503bf6b4bea11836ddc1d2f1188
Merge "add v3 API documentation"