From 1555736e3c1e0a66a99d0291934887250cd2e0cc Mon Sep 17 00:00:00 2001 From: Sean Dague Date: Wed, 20 Apr 2016 11:20:05 -0400 Subject: [PATCH] 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 | 13 +++-- api-ref/source/images.inc | 2 +- api-ref/source/os-agents.inc | 7 ++- api-ref/source/os-services.inc | 8 ++-- api-ref/source/parameters.yaml | 50 +++++++++++++++++--- api-ref/source/servers-action-crash-dump.inc | 2 - api-ref/source/servers-actions.inc | 6 +-- api-ref/source/servers-multiple-create.inc | 4 +- tox.ini | 7 +-- 9 files changed, 71 insertions(+), 28 deletions(-) diff --git a/api-ref/ext/rest_parameters.py b/api-ref/ext/rest_parameters.py index 7c5134cb5e08..88e75134342b 100644 --- a/api-ref/ext/rest_parameters.py +++ b/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, - "No field definition for %s found in %s. Skipping." % - (ref, fpath)) + "%s:%s " % ( + self.state_machine.node.source, + 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 diff --git a/api-ref/source/images.inc b/api-ref/source/images.inc index 429dce48e3f7..50cb58b14db5 100644 --- a/api-ref/source/images.inc +++ b/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 diff --git a/api-ref/source/os-agents.inc b/api-ref/source/os-agents.inc index 4e60d6fe129e..f250e8853800 100644 --- a/api-ref/source/os-agents.inc +++ b/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 - diff --git a/api-ref/source/os-services.inc b/api-ref/source/os-services.inc index aaa90b67818d..e0ab2ccc3317 100644 --- a/api-ref/source/os-services.inc +++ b/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 -------- diff --git a/api-ref/source/parameters.yaml b/api-ref/source/parameters.yaml index d15d7a06af10..09a5a614df56 100644 --- a/api-ref/source/parameters.yaml +++ b/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. diff --git a/api-ref/source/servers-action-crash-dump.inc b/api-ref/source/servers-action-crash-dump.inc index 9efec47e9f22..580501122e98 100644 --- a/api-ref/source/servers-action-crash-dump.inc +++ b/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 -------- - diff --git a/api-ref/source/servers-actions.inc b/api-ref/source/servers-actions.inc index 9020be455a9e..bf9b8509ff2a 100644 --- a/api-ref/source/servers-actions.inc +++ b/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 - :language: javascript + .. literalinclude:: ../../doc/api_samples/os-floating-ips/floating-ips-create-resp.json + :language: javascript Response -------- diff --git a/api-ref/source/servers-multiple-create.inc b/api-ref/source/servers-multiple-create.inc index 23e0c3e504c1..32731db13853 100644 --- a/api-ref/source/servers-multiple-create.inc +++ b/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 diff --git a/tox.ini b/tox.ini index 8af415dd71e2..89bcad806532 100644 --- a/tox.ini +++ b/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