Final warnings removals for api-ref

This removes the final warnings from the api-ref code base, and flips
the sphinx switch to enforce warnings as errors.

It also adds code to the rest_parameters extension to make it more
clear where a problem is when it comes to included parameters. This
puts us in a place where we can start doing the file per file look at
content.

Part of bp:api-ref-in-rst

Change-Id: Ic2c99d96d6addcafa00b9f16785c2fe59b1798d3

api-ref/ext/rest_parameters.py

@@ -141,10 +141,17 @@ class RestParametersDirective(Table):
                 if ref in lookup:
                     new_content.append((name, lookup[ref]))
                 else:
+                    # TODO(sdague): this provides a kind of confusing
+                    # error message because env.warn isn't meant to be
+                    # used this way, however it does provide a way to
+                    # track down where the parameters list is that is
+                    # wrong. So it's good enough for now.
                     self.env.warn(
-                        self.env.docname,
+                        "%s:%s " % (
-                        "No field definition for %s found in %s. Skipping." %
+                            self.state_machine.node.source,
-                        (ref, fpath))
+                            self.state_machine.node.line),
+                        ("No field definition for ``%s`` found in ``%s``. "
+                         " Skipping." % (ref, fpath)))
 
         # self.app.info("New content %s" % new_content)
         self.yaml = new_content

api-ref/source/images.inc

@@ -70,7 +70,7 @@ Response
    :language: javascript
 
 List Images With Details
-==================
+========================
 
 .. rest_method:: GET //v2.1/{tenant_id}/images/detail
 

api-ref/source/os-agents.inc

@@ -29,7 +29,7 @@ Request
 .. rest_parameters:: parameters.yaml
 
   - tenant_id: tenant_id
-  - hypervisor: hypervisor
+  - hypervisor: hypervisor_type
   - architecture: architecture
   - os: os
   - url: url
@@ -46,7 +46,7 @@ Response
 
 .. rest_parameters:: parameters.yaml
 
-  - hypervisor: hypervisor
+  - hypervisor: hypervisor_type
   - architecture: architecture
   - os: os
   - url: url
@@ -79,7 +79,7 @@ Request
   - tenant_id: tenant_id
   - agent_id: agent_id
   - architecture: architecture
-  - hypervisor: hypervisor
+  - hypervisor: hypervisor_type
   - url: url
   - md5hash: md5hash
   - version: version
@@ -156,4 +156,3 @@ Response
 
 .. literalinclude:: ../../doc/api_samples/os-agents/agent-update-put-resp.json
    :language: javascript
-

api-ref/source/os-services.inc

@@ -42,11 +42,11 @@ Response
   - binary: binary
   - disabled_reason: disabled_reason
   - host: host
-  - state: state
+  - state: service_state
   - status: status
-  - updated_at: updated_at
+  - updated_at: updated
   - forced_down: forced_down
-  - zone: zone
+  - zone: OS-EXT-AZ:availability_zone
 
 **Example List Compute Services: JSON response**
 
@@ -202,7 +202,7 @@ Request
 .. rest_parameters:: parameters.yaml
 
   - tenant_id: tenant_id
-  - service_id: service_id
+  - service_id: service_id_path
 
 Response
 --------

api-ref/source/parameters.yaml

@@ -64,12 +64,6 @@ attachment_id:
   in: path
   required: true
   type: string
-binary:
-  description: |
-    The binary name of the service.
-  in: path
-  required: true
-  type: string
 cell_id:
   description: |
     The UUID of the cell.
@@ -238,6 +232,12 @@ server_id_path:
   in: path
   required: true
   type: string
+service_id_path:
+  in: path
+  required: true
+  type: int
+  description: |
+    The id of the service
 snapshot_id_2:
   description: |
     The UUID of the snapshot.
@@ -686,6 +686,12 @@ availability_zone:
   in: body
   required: false
   type: string
+binary:
+  description: |
+    The binary name of the service.
+  in: body
+  required: true
+  type: string
 block_device_mapping_v2:
   description: |
     Enables fine grained control of the block device mapping for an instance. This
@@ -976,6 +982,14 @@ force:
   in: body
   required: false
   type: boolean
+forced_down:
+  in: body
+  required: true
+  type: boolean
+  description: |
+    Whether or not this service was forced down manually by an
+    adminstrator. This value is useful to know that some 3rd party has
+    verified the service should be marked down.
 forceDelete:
   description: |
     The action.
@@ -1048,6 +1062,12 @@ host_status:
   in: body
   required: true
   type: string
+hypervisor_type:
+  in: body
+  required: true
+  type: string
+  description: |
+    The hypervisor type for the agent. Currently only ``xen`` is supported.
 id:
   description: |
     The security group name or UUID.
@@ -1891,6 +1911,24 @@ servers:
   in: body
   required: true
   type: array
+service:
+  in: body
+  required: true
+  type: object
+  description: |
+    Object representing a compute service
+services:
+  in: body
+  required: true
+  type: array
+  description: |
+    An array of service objects
+service_state:
+  in: body
+  required: true
+  type: string
+  description: |
+    The state of the service. One of ``up`` or ``down``.
 shelve:
   description: |
     The action.

api-ref/source/servers-action-crash-dump.inc

@@ -25,7 +25,6 @@ Request
 
   - tenant_id: tenant_id
   - server_id: server_id
-  - trigger_crash_dump: trigger_crash_dump
 
 **Example Trigger crash dump: JSON request**
 
@@ -34,4 +33,3 @@ Request
 
 Response
 --------
-

api-ref/source/servers-actions.inc

@@ -56,10 +56,10 @@ Request
   - fixed_address: fixed_address
 
 .. TODO(gmann) Need to create the sample file for this action.
-**Example Add (Associate) Floating Ip (Addfloatingip Action): JSON request**
+   **Example Add (Associate) Floating Ip (Addfloatingip Action): JSON request**
 
-.. literalinclude:: ../../doc/api_samples/os-floating-ips/floating-ips-create-resp.json
+   .. literalinclude:: ../../doc/api_samples/os-floating-ips/floating-ips-create-resp.json
-   :language: javascript
+      :language: javascript
 
 Response
 --------

api-ref/source/servers-multiple-create.inc

@@ -36,7 +36,7 @@ Request
   - imageRef: imageRef
   - flavorRef: flavorRef
   - networks: networks
-  - uuid: uuid
+  - uuid: network_uuid
   - port: port
   - fixed_ip: fixed_ip
   - name: name
@@ -104,7 +104,7 @@ Request
   - imageRef: imageRef
   - flavorRef: flavorRef
   - networks: networks
-  - uuid: uuid
+  - uuid: network_uuid
   - port: port
   - fixed_ip: fixed_ip
   - name: name

tox.ini

@@ -86,12 +86,12 @@ commands = {posargs}
 
 [testenv:docs]
 commands =
-  rm -rf doc/source/api doc/build api-guide/build
+  rm -rf doc/source/api doc/build api-guide/build api-ref/build
   python setup.py build_sphinx
   bash -c '! find doc/ -type f -name *.json | xargs -t -n1 python -m json.tool 2>&1 > /dev/null | grep -B1 -v ^python'
   oslo-config-generator --config-file=etc/nova/nova-config-generator.conf
   sphinx-build -W -b html api-guide/source api-guide/build/html
-  sphinx-build -b html api-ref/source api-ref/build/html
+  sphinx-build -W -b html api-ref/source api-ref/build/html
 
 [testenv:api-guide]
 # This environment is called from CI scripts to test and publish
@@ -115,7 +115,8 @@ commands =
 # ignoring the duplicate stanzas warning.
 install_command = pip install -U --force-reinstall {opts} {packages}
 commands =
-  sphinx-build -b html -d api-ref/build/doctrees api-ref/source api-ref/build/html
+  rm -rf api-ref/build
+  sphinx-build -W -b html -d api-ref/build/doctrees api-ref/source api-ref/build/html
 
 [testenv:bandit]
 commands = bandit -c bandit.yaml -r nova -n 5 -ll