[api-ref] Minor text clean-up, formatting

- Cleaned up some wording, and formatted
  two rst notes.
- Moved cloudpipe.inc in index.rst to be located
  with other deprecated apis.

Change-Id: Ic3740540e8cc626110c77214acf87338e1abdd76

api-ref/source/index.rst

@@ -4,9 +4,9 @@
  Compute API
 =============
 
-This is a reference for the Openstack Compute API which is provided by Nova
+This is a reference for the Openstack Compute API which is provided by the Nova
-project. For getting more document about the basic concept of API, please
+project. To learn more about the Openstack Compute API concepts, please refer to
-refer to `API guide <http://developer.openstack.org/api-guide/compute/index.html>`_
+the `API guide <http://developer.openstack.org/api-guide/compute/index.html>`_.
 
 .. rest_expand_all::
 
@@ -41,7 +41,6 @@ refer to `API guide <http://developer.openstack.org/api-guide/compute/index.html
 .. include:: os-assisted-volume-snapshots.inc
 .. include:: os-availability-zone.inc
 .. include:: os-cells.inc
-.. include:: os-cloudpipe.inc
 .. include:: os-consoles.inc
 .. include:: os-hosts.inc
 .. include:: os-hypervisors.inc
@@ -54,6 +53,7 @@ refer to `API guide <http://developer.openstack.org/api-guide/compute/index.html
 .. include:: os-services.inc
 .. include:: os-simple-tenant-usage.inc
 .. include:: os-server-external-events.inc
+.. include:: os-cloudpipe.inc
 .. include:: extensions.inc
 .. include:: os-certificates.inc
 .. include:: os-networks.inc

api-ref/source/servers.inc

@@ -38,11 +38,9 @@ You can specify one or more networks to which the server connects at
 launch time. Users can also specify a specific port on the network or
 the fixed IP address to assign to the server interface.
 
-    **Note**
+.. note:: You can use both IPv4 and IPv6 addresses as access addresses,
-
+          and you can assign both addresses simultaneously. You can update
-    You can use both IPv4 and IPv6 addresses as access addresses and you
+          access addresses after you create a server.
-    can assign both addresses simultaneously. You can update access
-    addresses after you create a server.
 
 **Server personality**
 
@@ -61,10 +59,10 @@ Follow these guidelines when you inject files:
    determines the maximum size of the file contents. The image that you
    use to create the server determines this value.
 
-       **Note**
+   .. note::
 
-       The maximum limit refers to the number of bytes in the decoded
+      The maximum limit refers to the number of bytes in the decoded
-       data and not to the number of characters in the encoded data.
+      data and not to the number of characters in the encoded data.
 
 -  The ``maxPersonality`` absolute limit defines the maximum number of
    file path and content pairs that you can supply. The compute provider
@@ -186,7 +184,7 @@ Response
   - links: links
   - name: server_name
 
-**Example List Servers: JSON response**
+**Example List Servers**
 
 .. literalinclude:: ../../doc/api_samples/servers/servers-list-resp.json
    :language: javascript
@@ -226,20 +224,20 @@ request.
 
 .. note:: Starting with microversion 2.37 the ``networks`` field is required.
 
-Preconditions
+**Preconditions**
 
 - The user must have sufficient server quota to create the number of
   servers requested.
 - The connection to the Image service is valid.
 
-Asynchronous postconditions
+**Asynchronous postconditions**
 
 - With correct permissions, you can see the server status as
   ``ACTIVE`` through API calls.
 - With correct access, you can see the created server in the compute
   node that OpenStack Compute manages.
 
-Troubleshooting
+**Troubleshooting**
 
 - If the server status remains ``BUILDING`` or shows another error
   status, the request failed. Ensure you meet the preconditions then
@@ -311,7 +309,7 @@ Request
   - OS-DCF:diskConfig: OS-DCF:diskConfig
   - description: server_description
 
-**Example Create Server: JSON request**
+**Example Create Server**
 
 .. literalinclude:: ../../doc/api_samples/servers/server-create-req.json
    :language: javascript
@@ -367,7 +365,7 @@ Response
   - OS-EXT-SERV-ATTR:root_device_name: server_root_device_name
   - OS-EXT-SERV-ATTR:user_data: server_user_data
 
-**Example Create Server: JSON response**
+**Example Create Server**
 
 .. literalinclude:: ../../doc/api_samples/servers/server-create-resp.json
    :language: javascript
@@ -525,7 +523,7 @@ Response
   - OS-EXT-SERV-ATTR:root_device_name: server_root_device_name
   - OS-EXT-SERV-ATTR:user_data: server_user_data
 
-**Example List Servers Detailed: JSON response**
+**Example List Servers Detailed**
 
 .. literalinclude:: /../../doc/api_samples/servers/servers-details-resp.json
    :language: javascript
@@ -548,7 +546,7 @@ To hide ``addresses`` information for instances in a certain state, set the ``os
 
 HostId is unique per account and is not globally unique.
 
-Preconditions
+**Preconditions**
 
 The server must exist.
 
@@ -562,7 +560,6 @@ Request
 
 .. rest_parameters:: parameters.yaml
 
-
   - server_id: server_id_path
 
 Response
@@ -612,7 +609,7 @@ Response
   - OS-EXT-SERV-ATTR:root_device_name: server_root_device_name
   - OS-EXT-SERV-ATTR:user_data: server_user_data
 
-**Example Show Server Details: JSON response**
+**Example Show Server Details**
 
 .. literalinclude:: ../../doc/api_samples/servers/server-get-resp.json
    :language: javascript
@@ -634,7 +631,6 @@ Request
 
 .. rest_parameters:: parameters.yaml
 
-
   - server_id: server_id_path
   - accessIPv4: accessIPv4_in
   - accessIPv6: accessIPv6_in
@@ -642,7 +638,7 @@ Request
   - OS-DCF:diskConfig: OS-DCF:diskConfig
   - description: server_description
 
-**Example Update server name: JSON request**
+**Example Update server name**
 
 .. literalinclude:: ../../doc/api_samples/servers/server-update-req.json
    :language: javascript
@@ -706,7 +702,7 @@ Response
   - OS-EXT-SERV-ATTR:root_device_name: server_root_device_name
   - OS-EXT-SERV-ATTR:user_data: server_user_data
 
-**Example Update server name: JSON response**
+**Example Update server name**
 
 .. literalinclude:: ../../doc/api_samples/servers/server-update-resp.json
    :language: javascript
@@ -718,7 +714,7 @@ Delete Server
 
 Deletes a server.
 
-Preconditions
+**Preconditions**
 
 - The server must exist.
 - Anyone can delete a server when the status of the server is not
@@ -726,7 +722,7 @@ Preconditions
 - If the server is locked, you must have administrator privileges to
   delete the server.
 
-Asynchronous postconditions
+**Asynchronous postconditions**
 
 - With correct permissions, you can see the server status as
   ``DELETED`` through API calls.
@@ -735,7 +731,7 @@ Asynchronous postconditions
 - The server managed by OpenStack Compute is deleted on the compute
   node.
 
-Troubleshooting
+**Troubleshooting**
 
 - If server status remains in ``deleting`` status or another error
   status, the request failed. Ensure that you meet the
@@ -764,7 +760,6 @@ Request
 
 .. rest_parameters:: parameters.yaml
 
-
   - server_id: server_id_path
 
 Response

api-ref/source/urls.inc

@@ -4,20 +4,20 @@
  Service URLs
 ==============
 
-All API calls through the rest of this document require authentication
+All API calls described throughout the rest of this document require
-with the OpenStack Identity service. They also required a base
+authentication with the OpenStack Identity service. After authentication,
-``service url`` that is extracted from the Identity token of type
+a base ``service url`` can be extracted from the Identity token of type
-``compute``. This will be the root url that every call below will be
+``compute``. This ``service url`` will be the root url that every API call
-added to build a full path.
+uses to build a full path.
 
 For instance, if the ``service url`` is
 ``http://mycompute.pvt/compute/v2.1`` then the full API call for
 ``/servers`` is ``http://mycompute.pvt/compute/v2.1/servers``.
 
-Depending on the deployment the compute service url might be http or
+Depending on the deployment, the Compute ``service url`` might be http or
 https, a custom port, a custom path, and include your tenant id. The
 only way to know the urls for your deployment is by using the service
-catalog. The compute URL should never be hard coded in applications,
+catalog. The Compute URL should never be hard coded in applications,
 even if they are only expected to work at a single site. It should
 always be discovered from the Identity token.
 

api-ref/source/versions.inc

@@ -9,10 +9,10 @@ supports versioning. There are two kinds of versions in Nova.
 
 - ''major versions'', which have dedicated urls
 - ''microversions'', which can be requested through the use of the
-  ``X-OpenStack-Nova-API-Version`` header or since microversion 2.27
+  ``X-OpenStack-Nova-API-Version`` header, or since microversion 2.27
   the ``OpenStack-API-Version`` header may also be used.
 
-For more detail about Microversion, please reference:
+For more details about Microversions, please reference:
 `Microversions
 <http://developer.openstack.org/api-guide/compute/microversions.html>`_