Improve formats of the Compute API guide

Replace the 'NOTE' and 'TODO' words with
the note and todo directives in the Compute API guide.

Improve some format in the guide.
e.g. Fix unnecessary bold characters.

Change-Id: I7e9d6b8a5228886fd5de03d12482481d2b652666
Closes-Bug: #1558459

9 files changed, 152 insertions, 151 deletions

diff --git a/api-guide/source/conf.py b/api-guide/source/conf.py
index 6b0411a3d4..632115b1c2 100644
--- a/api-guide/source/conf.py
+++ b/api-guide/source/conf.py
@@ -31,7 +31,8 @@
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = ['openstackdocstheme']
+extensions = ['openstackdocstheme',
+              'sphinx.ext.todo']
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -39,6 +40,9 @@ templates_path = ['_templates']
 # The suffix of source filenames.
 source_suffix = '.rst'
 
+# The 'todo' and 'todolist' directive produce output.
+todo_include_todos = True
+
 # The encoding of source files.
 # source_encoding = 'utf-8-sig'
 
diff --git a/api-guide/source/general_info.rst b/api-guide/source/general_info.rst
index a32f62849b..873c81cd73 100644
--- a/api-guide/source/general_info.rst
+++ b/api-guide/source/general_info.rst
@@ -112,19 +112,19 @@ In this section we focus on this related to networking.
 
 -  **Port**
 
-   TODO
+   .. todo:: Add more details.
 
 -  **Floating IPs, Pools and DNS**
 
-   TODO
+   .. todo:: Add more details.
 
 -  **Security Groups**
 
-   TODO
+   .. todo:: Add more details.
 
 -  **Extended Networks**
 
-   TODO
+   .. todo:: Add more details.
 
 
 Administrator Concepts
@@ -222,9 +222,9 @@ on compute hosts rather than servers.
 -  **Hosts**
 
    Hosts are the *physical machines* that provide the resources for the virtual
-   servers created in Nova. They run a ``hypervisor`` (see definition below)
+   servers created in Nova. They run a **hypervisor** (see definition below)
    that handles the actual creation and management of the virtual servers.
-   Hosts also run the ``Nova compute service``, which receives requests from
+   Hosts also run the **Nova compute service**, which receives requests from
    Nova to interact with the virtual servers on that machine. When compute
    service receives a request, it calls the appropriate methods of the driver
    for that hypervisor in order to carry out the request. The driver acts as
@@ -282,7 +282,7 @@ Relationship with Volume API
 
 Here we discuss about Cinder's API and how Nova users volume UUIDs.
 
-TODO - add more details.
+.. todo:: add more details.
 
 Relationship with Image API
 ===========================
@@ -290,7 +290,7 @@ Relationship with Image API
 Here we discuss about Glance's API and how Nova uses image UUIDs.
 We also discuss how Nova proxies setting image metadata.
 
-TODO - add more details.
+.. todo:: add more details.
 
 Interactions with neutron and nova-network (deprecated)
 =======================================================
@@ -302,4 +302,4 @@ Here we discuss about Neutron's API and how Nova users port UUIDs.
 We also discuss Nova automatically creating ports, proxying security groups,
 and proxying floating IPs. Also talk about the APIs we do not proxy.
 
-TODO - add more details.
+.. todo:: add more details.
diff --git a/api-guide/source/index.rst b/api-guide/source/index.rst
index 48b5a43835..cd6901bd69 100644
--- a/api-guide/source/index.rst
+++ b/api-guide/source/index.rst
@@ -60,7 +60,7 @@ the following endpoints:
 
 * / - list of available versions
 * /v2 - the first version of the Compute API, uses extensions
-        (we call this Compute API v2.0)
+  (we call this Compute API v2.0)
 * /v2.1 - same API, except uses microversions
 
 While this guide concentrates on documenting the v2.1 API,
diff --git a/api-guide/source/microversions.rst b/api-guide/source/microversions.rst
index 1b202665ed..b1590123cb 100644
--- a/api-guide/source/microversions.rst
+++ b/api-guide/source/microversions.rst
@@ -27,24 +27,24 @@ There are multiple cases which you can resolve with microversions:
 
 - **Older clients with new cloud**
 
-Before using an old client to talk to a newer cloud, the old client can check
-the minimum version of microversions to verify whether the cloud is compatible
-with the old API. This prevents the old client from breaking with backwards
-incompatible API changes.
-
-Currently the minimum version of microversions is `2.1`, which is a
-microversion compatible with the legacy v2 API. That means the legacy v2 API
-user doesn't need to worry that their older client software will be broken when
-their cloud is upgraded with new versions. And the cloud operator doesn't need
-to worry that upgrading their cloud to newer versions will break any user with
-older clients that don't expect these changes.
+  Before using an old client to talk to a newer cloud, the old client can check
+  the minimum version of microversions to verify whether the cloud is
+  compatible with the old API. This prevents the old client from breaking with
+  backwards incompatible API changes.
+
+  Currently the minimum version of microversions is `2.1`, which is a
+  microversion compatible with the legacy v2 API. That means the legacy v2 API
+  user doesn't need to worry that their older client software will be broken
+  when their cloud is upgraded with new versions. And the cloud operator
+  doesn't need to worry that upgrading their cloud to newer versions will
+  break any user with older clients that don't expect these changes.
 
 - **User discovery of available features between clouds**
 
-The new features can be discovered by microversions. The user client should
-check the microversions firstly, and new features are only enabled when clouds
-support. In this way, the user client can work with clouds that have deployed
-different microversions simultaneously.
+  The new features can be discovered by microversions. The user client should
+  check the microversions firstly, and new features are only enabled when
+  clouds support. In this way, the user client can work with clouds that have
+  deployed different microversions simultaneously.
 
 Version Discovery
 =================
@@ -52,7 +52,7 @@ Version Discovery
 The Version API will return the minimum and maximum microversions. These values
 are used by the client to discover the API's supported microversion(s).
 
-Requests to '/' will get version info for all endpoints. A response would look
+Requests to `/` will get version info for all endpoints. A response would look
 as follows::
 
   {
@@ -86,12 +86,12 @@ as follows::
     ]
   }
 
-"version" is the maximum microversion, "min_version" is the minimum
+``version`` is the maximum microversion, ``min_version`` is the minimum
 microversion. If the value is the empty string, it means this endpoint doesn't
 support microversions; it is a legacy v2 API endpoint -- for example, the
 endpoint `http://openstack.example.com/v2/` in the above sample. The endpoint
 `http://openstack.example.com/v2.1/` supports microversions; the maximum
-microversion is '2.14', and the minimum microversion is '2.1'. The client
+microversion is `2.14`, and the minimum microversion is `2.1`. The client
 should specify a microversion between (and including) the minimum and maximum
 microversion to access the endpoint.
 
@@ -117,20 +117,20 @@ following header to specify the microversion::
 
 This acts conceptually like the "Accept" header. Semantically this means:
 
-* If neither `X-OpenStack-Nova-API-Version` nor `OpenStack-API-Version`
+* If neither ``X-OpenStack-Nova-API-Version`` nor ``OpenStack-API-Version``
   (specifying `compute`) is provided, act as if the minimum supported
   microversion was specified.
 
-* If both headers are provided, `OpenStack-API-Version` will be preferred.
+* If both headers are provided, ``OpenStack-API-Version`` will be preferred.
 
-* If `X-OpenStack-Nova-API-Version` or `OpenStack-API-Version` is provided,
+* If ``X-OpenStack-Nova-API-Version`` or ``OpenStack-API-Version`` is provided,
   respond with the API at that microversion. If that's outside of the range
   of microversions supported, return 406 Not Acceptable.
 
-* If `X-OpenStack-Nova-API-Version` or `OpenStack-API-Version` has a value
-  of ``latest`` (special keyword), act as if maximum was specified.
+* If ``X-OpenStack-Nova-API-Version`` or ``OpenStack-API-Version`` has a value
+  of `latest` (special keyword), act as if maximum was specified.
 
-.. warning:: The ``latest`` value is mostly meant for integration testing and
+.. warning:: The `latest` value is mostly meant for integration testing and
   would be dangerous to rely on in client code since microversions are not
   following semver and therefore backward compatibility is not guaranteed.
   Clients should always require a specific microversion but limit what is
@@ -149,7 +149,7 @@ the response::
 The first header specifies the microversion number of the API which was
 executed.
 
-The `Vary` header is used as a hint to caching proxies that the response
+The ``Vary`` header is used as a hint to caching proxies that the response
 is also dependent on the microversion and not just the body and query
 parameters. See :rfc:`2616` section 14.44 for details.
 
diff --git a/api-guide/source/paginated_collections.rst b/api-guide/source/paginated_collections.rst
index 08f7d137be..e817642bf2 100644
--- a/api-guide/source/paginated_collections.rst
+++ b/api-guide/source/paginated_collections.rst
@@ -4,18 +4,18 @@ Paginated collections
 
 To reduce load on the service, list operations return a maximum number
 of items at a time. The maximum number of items returned is determined
-by the compute provider. To navigate the collection, the *``limit``* and
-*``marker``* parameters can be set in the URI. For example:
+by the compute provider. To navigate the collection, the ``limit`` and
+``marker`` parameters can be set in the URI. For example:
 
 .. code::
 
     ?limit=100&marker=1234
 
-The *``marker``* parameter is the ID of the last item in the previous
+The ``marker`` parameter is the ID of the last item in the previous
 list. By default, the service sorts items by create time in descending order.
 When the service cannot identify a create time, it sorts items by ID. The
-*``limit``* parameter sets the page size. Both parameters are optional. If the
-client requests a *``limit``* beyond one that is supported by the deployment
+``limit`` parameter sets the page size. Both parameters are optional. If the
+client requests a ``limit`` beyond one that is supported by the deployment
 an overLimit (413) fault may be thrown. A marker with an invalid ID returns
 a badRequest (400) fault.
 
@@ -25,11 +25,11 @@ implementation does not contain ``previous`` links. The last
 page in the list does not contain a link to "next" page. The following examples
 illustrate three pages in a collection of servers. The first page was
 retrieved through a **GET** to
-``http://servers.api.openstack.org/v2.1/servers?limit=1``. In these
+`http://servers.api.openstack.org/v2.1/servers?limit=1`. In these
 examples, the *``limit``* parameter sets the page size to a single item.
 Subsequent links honor the initial page size. Thus, a client can follow
 links to traverse a paginated collection without having to input the
-*``marker``* parameter.
+``marker`` parameter.
 
 
 **Example: Servers collection: JSON (first page)**
diff --git a/api-guide/source/polling_changes.rst b/api-guide/source/polling_changes.rst
index bef656d39e..671ad89434 100644
--- a/api-guide/source/polling_changes.rst
+++ b/api-guide/source/polling_changes.rst
@@ -10,10 +10,10 @@ for changes within a specified time.
 
 The ``changes-since`` time or ``changes-before`` time is specified as
 an `ISO 8601 <https://en.wikipedia.org/wiki/ISO_8601>`__ dateTime
-(2011-01-24T17:08Z). The form for the timestamp is **CCYY-MM-DDThh:mm:ss**.
+(`2011-01-24T17:08Z`). The form for the timestamp is **CCYY-MM-DDThh:mm:ss**.
 An optional time zone may be written in by appending the form ±hh:mm
 which describes the timezone as an offset from UTC. When the timezone is
-not specified (2011-01-24T17:08), the UTC timezone is assumed.
+not specified (`2011-01-24T17:08`), the UTC timezone is assumed.
 
 The following situations need to be considered:
 
diff --git a/api-guide/source/server_concepts.rst b/api-guide/source/server_concepts.rst
index c3c0d3b3da..1ddf557e49 100644
--- a/api-guide/source/server_concepts.rst
+++ b/api-guide/source/server_concepts.rst
@@ -59,9 +59,9 @@ server status is one of the following values:
 
 -  ``SHUTOFF``: The server was powered down by the user, either through the
    OpenStack Compute API or from within the server. For example, the user
-   issued a ``shutdown -h`` command from within the server. If the OpenStack
-   Compute manager detects that the VM was powered down, it transitions the
-   server to the SHUTOFF status.
+   issued a :command:`shutdown -h` command from within the server.
+   If the OpenStack Compute manager detects that the VM was powered down,
+   it transitions the server to the SHUTOFF status.
 
 -  ``SOFT_DELETED``: The server is marked as deleted but will remain in the
    cloud for some configurable amount of time. While soft-deleted, an
@@ -93,8 +93,8 @@ are exposed to administrators:
   Refer to :nova-doc:`VM States <reference/vm-states.html>`.
 
 - task_state represents what is happening to the instance at the
-  current moment. These tasks can be generic, such as 'spawning', or specific,
-  such as 'block_device_mapping'. These task states allow for a better view into
+  current moment. These tasks can be generic, such as `spawning`, or specific,
+  such as `block_device_mapping`. These task states allow for a better view into
   what a server is doing.
 
 Server creation
@@ -102,24 +102,28 @@ Server creation
 
 Status Transition:
 
-``BUILD``
+- ``BUILD``
 
-``ACTIVE``
+  .. todo:: Add more details.
 
-``ERROR`` (on error)
+- ``ACTIVE``
 
-When you create a server, the operation asynchronously provisions a new
-server. The progress of this operation depends on several factors
-including location of the requested image, network I/O, host load, and
-the selected flavor. The progress of the request can be checked by
-performing a **GET** on /servers/*``id``*, which returns a progress
-attribute (from 0% to 100% complete). The full URL to the newly created
-server is returned through the ``Location`` header and is available as a
-``self`` and ``bookmark`` link in the server representation. Note that
-when creating a server, only the server ID, its links, and the
-administrative password are guaranteed to be returned in the request.
-You can retrieve additional attributes by performing subsequent **GET**
-operations on the server.
+  .. todo:: Add more details.
+
+- ``ERROR`` (on error)
+
+  When you create a server, the operation asynchronously provisions a new
+  server. The progress of this operation depends on several factors
+  including location of the requested image, network I/O, host load, and
+  the selected flavor. The progress of the request can be checked by
+  performing a **GET** on /servers/*{server_id}*, which returns a progress
+  attribute (from 0% to 100% complete). The full URL to the newly created
+  server is returned through the ``Location`` header and is available as a
+  ``self`` and ``bookmark`` link in the server representation. Note that
+  when creating a server, only the server ID, its links, and the
+  administrative password are guaranteed to be returned in the request.
+  You can retrieve additional attributes by performing subsequent **GET**
+  operations on the server.
 
 Server query
 ~~~~~~~~~~~~
@@ -144,31 +148,33 @@ For different user roles, the user has different query options set:
   the query options are different from the attribute naming in the servers API
   response.
 
-.. code::
 
-   Precondition:
-   there are 2 servers existing in cloud with following info:
+Precondition: there are 2 servers existing in cloud with following info::
 
-   "servers": [
-       {
-           "name": "t1",
-           "locked": "true",
-           ...
-       },
-       {
-           "name": "t2",
-           "locked": "false",
-           ...
-       }
-   ]
+  {
+      "servers": [
+          {
+              "name": "t1",
+              "locked": "true",
+              ...
+          },
+          {
+              "name": "t2",
+              "locked": "false",
+              ...
+          }
+      ]
+  }
+
+**Example: General user query server with administrator only options**
+
+Request with non-administrator context: ``GET /servers/detail?locked=1``
 
-   **Example: General user query server with administrator only options**
+Note that ``locked`` is returned through API layer starting from
+microversion 2.9.
 
-   Request with non-administrator context:
-   GET /servers/detail?locked=1
-   Note that 'locked' is not returned through API layer
+Response::
 
-   Response:
    {
        "servers": [
            {
@@ -182,12 +188,12 @@ For different user roles, the user has different query options set:
        ]
    }
 
-   **Example: Administrator query server with administrator only options**
+**Example: Administrator query server with administrator only options**
 
-   Request with administrator context:
-   GET /servers/detail?locked=1
+Request with administrator context: ``GET /servers/detail?locked=1``
+
+Response::
 
-   Response:
    {
        "servers": [
            {
@@ -213,14 +219,13 @@ There are also some special query options:
 - ``all_tenants`` is an administrator query option, which allows the
   administrator to query the servers in any tenant.
 
-.. code::
 
-   **Example: User query server with special keys changes-since or changes-before**
+**Example: User query server with special keys changes-since or changes-before**
+
+Request: ``GET /servers/detail``
 
-   Precondition:
-   GET /servers/detail
+Response::
 
-   Response:
    {
        "servers": [
            {
@@ -236,9 +241,10 @@ There are also some special query options:
        ]
    }
 
-   GET /servers/detail?changes-since='2015-12-16T15:55:52Z'
+Request: ``GET /servers/detail?changes-since='2015-12-16T15:55:52Z'``
+
+Response::
 
-   Response:
    {
        {
            "name": "t2",
@@ -247,9 +253,10 @@ There are also some special query options:
        }
    }
 
-   GET /servers/detail?changes-before='2015-12-16T15:55:52Z'
+Request: ``GET /servers/detail?changes-before='2015-12-16T15:55:52Z'``
+
+Response::
 
-   Response:
    {
        {
            "name": "t1",
@@ -258,9 +265,11 @@ There are also some special query options:
        }
    }
 
-   GET /servers/detail?changes-since='2015-12-10T15:55:52Z'&changes-before='2015-12-28T15:55:52Z'
+Request:
+``GET /servers/detail?changes-since='2015-12-10T15:55:52Z'&changes-before='2015-12-28T15:55:52Z'``
+
+Response::
 
-   Response:
    {
        "servers": [
            {
@@ -279,15 +288,11 @@ There are also some special query options:
 There are two kinds of matching in query options: Exact matching and
 regex matching.
 
-.. code::
-
-   **Example: User query server using exact matching on host**
+**Example: User query server using exact matching on host**
 
-   Precondition:
-   Request with administrator context:
-   GET /servers/detail
+Request with administrator context: ``GET /servers/detail``
 
-   Response:
+Response::
 
    {
        "servers": [
@@ -304,10 +309,9 @@ regex matching.
        ]
    }
 
-   Request with administrator context:
-   GET /servers/detail?host=devstack
+Request with administrator context: ``GET /servers/detail?host=devstack``
 
-   Response:
+Response::
 
    {
        "servers": [
@@ -319,13 +323,11 @@ regex matching.
        ]
    }
 
-   **Example: Query server using regex matching on name**
+**Example: Query server using regex matching on name**
 
-   Precondition:
-   Request with administrator context:
-   GET /servers/detail
+Request with administrator context: ``GET /servers/detail``
 
-   Response:
+Response::
 
    {
        "servers": [
@@ -348,10 +350,9 @@ regex matching.
        ]
    }
 
-   Request with administrator context:
-   GET /servers/detail?name=t1
+Request with administrator context: ``GET /servers/detail?name=t1``
 
-   Response:
+Response::
 
    {
        "servers": [
@@ -370,14 +371,12 @@ regex matching.
        ]
    }
 
-   **Example: User query server using exact matching on host and
-   regex matching on name**
+**Example: User query server using exact matching on host and regex
+matching on name**
 
-   Precondition:
-   Request with administrator context:
-   GET /servers/detail
+Request with administrator context: ``GET /servers/detail``
 
-   Response:
+Response::
 
    {
        "servers": [
@@ -399,10 +398,10 @@ regex matching.
        ]
    }
 
-   Request with administrator context:
-   GET /servers/detail?host=devstack1&name=test
+Request with administrator context:
+``GET /servers/detail?host=devstack1&name=test``
 
-   Response:
+Response::
 
    {
        "servers": [
@@ -414,16 +413,10 @@ regex matching.
        ]
    }
 
-               "name": "t2",
-               "updated": "2015-12-17T15:55:52Z"
-               ...
-           }
-       ]
-   }
+Request: ``GET /servers/detail?changes-since='2015-12-16T15:55:52Z'``
 
-   GET /servers/detail?changes-since='2015-12-16T15:55:52Z'
+Response::
 
-   Response:
    {
        {
            "name": "t2",
@@ -635,7 +628,7 @@ limit.
 Block Device Mapping
 ~~~~~~~~~~~~~~~~~~~~
 
-TODO: Add some description about BDM.
+.. todo:: Add some description about BDM.
 
 Scheduler Hints
 ~~~~~~~~~~~~~~~
@@ -706,7 +699,7 @@ assigned at creation time.
 
 **Example: Create server with access IP: JSON request**
 
-.. code::
+.. code-block:: json
 
     {
         "server": {
@@ -724,7 +717,7 @@ assigned at creation time.
 
 **Example: Create server with multiple access IPs: JSON request**
 
-.. code::
+.. code-block:: json
 
     {
         "server": {
@@ -803,7 +796,7 @@ a cloud:
    This process can be repeated until the whole cloud has been updated,
    usually using a pool of empty hosts instead of just one.
 
-- **Resource Optimization**
+-  **Resource Optimization**
 
    To reduce energy usage, some cloud operators will try and move
    servers so they fit into the minimum number of hosts, allowing
diff --git a/api-guide/source/users.rst b/api-guide/source/users.rst
index 7128a5ac66..e09cbb6d16 100644
--- a/api-guide/source/users.rst
+++ b/api-guide/source/users.rst
@@ -27,7 +27,7 @@ Keystone middleware is used to authenticate users and identify their roles.
 The Compute API uses these roles, along with oslo.policy, to decide
 what the user is authorized to do.
 
-TODO - link to compute admin guide for details.
+.. todo:: link to compute admin guide for details.
 
 Personas used in this guide
 ===========================
@@ -47,11 +47,15 @@ cloud administrator permissions, such as a read-only role that is able to view
 a lists of servers for a specific tenant but is not able to perform any
 actions on any of them.
 
-Note: this is not attempting to be an exhaustive set of personas that consider
-various facets of the different users but instead aims to be a minimal set of
-users such that we use a consistent terminology throughout this document.
+.. note::
 
-TODO - could assign names to these users, or similar, to make it more "real".
+  This is not attempting to be an exhaustive set of personas that consider
+  various facets of the different users but instead aims to be a minimal set of
+  users such that we use a consistent terminology throughout this document.
+
+.. todo::
+
+  could assign names to these users, or similar, to make it more "real".
 
 Discovering Policy
 ==================
@@ -59,4 +63,4 @@ Discovering Policy
 An API to discover what actions you are authorized to perform is still a work
 in progress. Currently this reported by a HTTP 403 error.
 
-TODO - link to the doc on errors.
+.. todo:: link to the doc on errors.
diff --git a/api-guide/source/versions.rst b/api-guide/source/versions.rst
index ee8ce9fed6..fdb1ffe217 100644
--- a/api-guide/source/versions.rst
+++ b/api-guide/source/versions.rst
@@ -4,8 +4,8 @@ Versions
 
 The OpenStack Compute API uses both a URI and a MIME type versioning
 scheme. In the URI scheme, the first element of the path contains the
-target version identifier (e.g. https://servers.api.openstack.org/
-v2.1/...). The MIME type versioning scheme uses HTTP content negotiation
+target version identifier (e.g. `https://servers.api.openstack.org/
+v2.1/`...). The MIME type versioning scheme uses HTTP content negotiation
 where the ``Accept`` or ``Content-Type`` headers contains a MIME type
 that identifies the version (application/vnd.openstack.compute.v2.1+json).
 A version MIME type is always linked to a base MIME type, such as
@@ -37,7 +37,7 @@ Permanent Links
 
 The MIME type versioning approach allows for creating of permanent
 links, because the version scheme is not specified in the URI path:
-https://api.servers.openstack.org/224532/servers/123.
+`https://api.servers.openstack.org/224532/servers/123`.
 
 If a request is made without a version specified in the URI or via HTTP
 headers, then a multiple-choices response (300) follows that provides
@@ -99,12 +99,12 @@ everything following that truncated) returned from the authentication system.
 
 You can also obtain additional information about a specific version by
 performing a **GET** on the base version URL (such as,
-``https://servers.api.openstack.org/v2.1/``). Version request URLs must
-always end with a trailing slash (``/``). If you omit the slash, the
+`https://servers.api.openstack.org/v2.1/`). Version request URLs must
+always end with a trailing slash (`/`). If you omit the slash, the
 server might respond with a 302 redirection request.
 
 For examples of the list versions and get version details requests and
-responses, see `*API versions*
+responses, see `API versions
 <https://developer.openstack.org/api-ref/compute/#api-versions>`__.
 
 The detailed version response contains pointers to both a human-readable