Add missing preamble for v3 and v3-ext

The api-ref site had a short blurb about the resources listed
in the document, add that back.

Change-Id: I2bac40a250a5b73fb70320d598a12c34c359e3c2

api-ref/source/v3-ext/index.rst

@@ -4,6 +4,13 @@
  Identity API v3 extensions (CURRENT)
 ======================================
 
+This page describes these Identity API v3 extensions:
+
+* `OS-ENDPOINT-POLICY API`_
+* `OS-INHERIT API`_
+* `OS-OAUTH1 API`_
+* `OS-TRUST API`_
+
 .. rest_expand_all::
 
 .. include:: endpoint-policy.inc

api-ref/source/v3/authenticate-v3.inc

@@ -1,8 +1,8 @@
 .. -*- rst -*-
 
-==================================================
-Authentication and token management (auth, tokens)
-==================================================
+=====================================
+ Authentication and token management
+=====================================
 
 In exchange for a set of authentication credentials, the Identity
 service generates tokens. A token represents the authenticated

api-ref/source/v3/credentials.inc

@@ -1,8 +1,8 @@
 .. -*- rst -*-
 
-=========================
-Credentials (credentials)
-=========================
+=============
+ Credentials
+=============
 
 In exchange for a set of authentication credentials that the user
 submits, the Identity service generates and returns a token. A

api-ref/source/v3/domains-config-v3.inc

@@ -1,8 +1,8 @@
 .. -*- rst -*-
 
-==================================================================
-Domain configuration (domains, config) (since v3.4) (EXPERIMENTAL)
-==================================================================
+======================
+ Domain configuration
+======================
 
 You can manage domain-specific configuration options.
 

api-ref/source/v3/domains.inc

@@ -1,8 +1,8 @@
 .. -*- rst -*-
 
-=======================================
-Domains (domains, users, groups, roles)
-=======================================
+=========
+ Domains
+=========
 
 A domain is a collection of users, groups, and projects. Each group
 and project is owned by exactly one domain.

api-ref/source/v3/groups.inc

@@ -1,8 +1,8 @@
 .. -*- rst -*-
 
-======================
-Groups (groups, users)
-======================
+========
+ Groups
+========
 
 A group is a collection of users. Each group is owned by a domain.
 

api-ref/source/v3/index.rst

@@ -4,6 +4,39 @@
  Identity API v3 (CURRENT)
 ===========================
 
+The Identity service generates authentication tokens that permit access to the
+OpenStack services REST APIs. Clients obtain this token and the URL endpoints
+for other service APIs by supplying their valid credentials to the
+authentication service.
+
+Each time you make a REST API request to an OpenStack service, you supply your
+authentication token in the X-Auth-Token request header.
+
+Like most OpenStack projects, OpenStack Identity protects its APIs by defining
+policy rules based on a role-based access control (RBAC) approach.
+
+The Identity service configuration file sets the name and location of a JSON
+policy file that stores these rules.
+
+For information about Identity API protection, see
+`Identity API protection with role-based access control (RBAC)
+<http://docs.openstack.org/admin-guide/identity_service_api_protection.html>`_
+in the OpenStack Cloud Administrator Guide.
+
+This page lists the Identity API operations in the following order:
+
+* `Authentication and token management`_
+* `Credentials`_
+* `Domains`_
+* `Domain configuration`_
+* `Groups`_
+* `Policies`_
+* `Projects`_
+* `Regions`_
+* `Roles`_
+* `Service catalog and endpoints`_
+* `Users`_
+
 .. rest_expand_all::
 
 .. include:: authenticate-v3.inc

api-ref/source/v3/policies.inc

@@ -1,8 +1,8 @@
 .. -*- rst -*-
 
-===================
-Policies (policies)
-===================
+==========
+ Policies
+==========
 
 A policy is an arbitrarily serialized policy engine rule set to be
 consumed by a remote service.

api-ref/source/v3/projects.inc

@@ -1,8 +1,8 @@
 .. -*- rst -*-
 
-=========================================
-Projects (projects, users, groups, roles)
-=========================================
+==========
+ Projects
+==========
 
 A project is the base unit of ownership. Resources are owned by a
 specific project. A project is owned by a specific domain.

api-ref/source/v3/regions-v3.inc

@@ -1,8 +1,8 @@
 .. -*- rst -*-
 
-==============================
-Regions (regions) (since v3.2)
-==============================
+=========
+ Regions
+=========
 
 A region is a general division of an OpenStack deployment. You can
 associate zero or more sub-regions with a region to create a tree-

api-ref/source/v3/service-catalog.inc

@@ -1,8 +1,8 @@
 .. -*- rst -*-
 
-===================================================
-Service catalog and endpoints (services, endpoints)
-===================================================
+===============================
+ Service catalog and endpoints
+===============================
 
 A service is an OpenStack web service that you can access through a
 URL, or endpoint.

api-ref/source/v3/users.inc

@@ -1,8 +1,8 @@
 .. -*- rst -*-
 
-======================================
-Users (users, groups, projects, roles)
-======================================
+=======
+ Users
+=======
 
 A user is an individual API consumer that is owned by a domain. A
 role explicitly associates a user with projects or domains. A user