openstack/nova
Code Issues Proposed changes
db294b1e33
nova/placement-api-ref/source/index.rst

33 lines
1014 B
ReStructuredText
Raw Normal View History

Structure for simply managing placement-api-ref This consists of a duplicate of the [nova-]api-ref setup and conf.py along with tooling to fail the tox -edocs target when a route that is defined in nova.api.openstack.placement.handler.ROUTE_DECLARATIONS is not present in placement-api-ref/source/index.rst. tools/placement_api_docs.py will report which routes are missing. Though completely gameable (as demonstrated in the current lame index.rst) it's better than nothing and provides some useful structuring on what to do next. It's also the case that the 'docs' target in tox is not part of gating. The response for GET / is in place with the necessary parameters.yaml for it to be correctly described. The 'get-root.json' file provides the JSON of the expected response. The expectation is that later commits will add information for other urls and their JSON files will be named method-path-separated-by-dash.json with a request/response qualifier as necessary. Followup patches will add other routes. A new parameters.yaml is used instead of reusing the one from api-ref as there isn't a lot of expected overlap and having a separate file will ease eventual extraction. Running tox -eplacement-api-ref will generate the docs for review, with output in placement-api-ref/build/html/index.html. This will be hooked up with CI to deploy the generated docs, eventually. Change-Id: Ifb4d91d39db0e49b55952e37cdfc9f63dcd37aa3
2016-12-09 21:47:25 +00:00
:tocdepth: 2
===============
Placement API
===============
Fix OpenStack capitalization Reviewing the Placement API, I noticed wrong OpenStack capitalization. Fix the docs and some strings as well. Change-Id: I14a2443687a0d517ece80e794e7ef0d4e165af6f
2018-01-07 12:34:22 +01:00
This is a reference for the OpenStack Placement API. To learn more about
doc: Start using openstackdoctheme's extlink extension This ensures we have version-specific references to other projects [1]. Note that this doesn't mean the URLs are actually valid - we need to do more work (linkcheck?) here, but it's an improvement nonetheless. [1] https://docs.openstack.org/openstackdocstheme/latest/#external-link-helper Change-Id: Ifb99e727110c4904a85bc4a13366c2cae300b8df
2018-02-05 15:15:34 +00:00
OpenStack Placement API concepts, please refer to the :nova-doc:`Placement
Introduction <user/placement.html>`.
Structure for simply managing placement-api-ref This consists of a duplicate of the [nova-]api-ref setup and conf.py along with tooling to fail the tox -edocs target when a route that is defined in nova.api.openstack.placement.handler.ROUTE_DECLARATIONS is not present in placement-api-ref/source/index.rst. tools/placement_api_docs.py will report which routes are missing. Though completely gameable (as demonstrated in the current lame index.rst) it's better than nothing and provides some useful structuring on what to do next. It's also the case that the 'docs' target in tox is not part of gating. The response for GET / is in place with the necessary parameters.yaml for it to be correctly described. The 'get-root.json' file provides the JSON of the expected response. The expectation is that later commits will add information for other urls and their JSON files will be named method-path-separated-by-dash.json with a request/response qualifier as necessary. Followup patches will add other routes. A new parameters.yaml is used instead of reusing the one from api-ref as there isn't a lot of expected overlap and having a separate file will ease eventual extraction. Running tox -eplacement-api-ref will generate the docs for review, with output in placement-api-ref/build/html/index.html. This will be hooked up with CI to deploy the generated docs, eventually. Change-Id: Ifb4d91d39db0e49b55952e37cdfc9f63dcd37aa3
2016-12-09 21:47:25 +00:00
placement: Document request headers in api-ref Briefly document in the Placement API reference: a) the use of Content-Type: application/json b) how to use microversion headers, including a link to the main Microversions reference. Change-Id: I60d7b9dfe4f1c50fc50eaf07a04848c220ffcf62
2017-11-20 09:38:58 -06:00
The Placement API uses JSON for data exchange. As such, the ``Content-Type``
header for APIs sending data payloads in the request body (i.e. ``PUT`` and
``POST``) must be set to ``application/json`` unless otherwise noted.
Structure for simply managing placement-api-ref This consists of a duplicate of the [nova-]api-ref setup and conf.py along with tooling to fail the tox -edocs target when a route that is defined in nova.api.openstack.placement.handler.ROUTE_DECLARATIONS is not present in placement-api-ref/source/index.rst. tools/placement_api_docs.py will report which routes are missing. Though completely gameable (as demonstrated in the current lame index.rst) it's better than nothing and provides some useful structuring on what to do next. It's also the case that the 'docs' target in tox is not part of gating. The response for GET / is in place with the necessary parameters.yaml for it to be correctly described. The 'get-root.json' file provides the JSON of the expected response. The expectation is that later commits will add information for other urls and their JSON files will be named method-path-separated-by-dash.json with a request/response qualifier as necessary. Followup patches will add other routes. A new parameters.yaml is used instead of reusing the one from api-ref as there isn't a lot of expected overlap and having a separate file will ease eventual extraction. Running tox -eplacement-api-ref will generate the docs for review, with output in placement-api-ref/build/html/index.html. This will be hooked up with CI to deploy the generated docs, eventually. Change-Id: Ifb4d91d39db0e49b55952e37cdfc9f63dcd37aa3
2016-12-09 21:47:25 +00:00
.. rest_expand_all::
[placement] Add x-openstack-request-id in API ref Add the description about 'x-openstack-request-id' in the request and the response headers. Change-Id: I6ffdfbacb81660b89d7bf8ba83dbab1aa25a80bd Closes-Bug: #1733496
2017-11-27 11:57:38 +09:00
.. include:: request-ids.inc
[placement] Split api-ref topics per file For more convinient text management each ROUTE_DECLARATIONS has its own inc file in api-ref. Change-Id: Ia2fd62ae7f401cad34ee7c2b355c9a5ab1c93f6b
2017-03-24 18:42:56 +03:00
.. include:: root.inc
.. include:: resource_providers.inc
[placement] Add api-ref for GET resource provider This provides simple documentation of the response body and path parameters when listing a single resource provider. Change-Id: I84d472067e4365d59cab4863f87df9d24718701f
2017-05-24 11:26:59 +03:00
.. include:: resource_provider.inc
[placement] Add api-ref for resource classes This provides simple documentation of the path, request and response body parameters when listing, creating, updating and deleting a resource class. Change-Id: I4038d116d53b68344282ef59f9f01753766d2ef8
2017-05-24 14:21:03 +03:00
.. include:: resource_classes.inc
.. include:: resource_class.inc
[placement] Add api-ref for GET RP inventories This provides simple documentation of the response body and path parameters when listing resource provider inventories. Change-Id: Id4ed2450ab70fc63d47dabb21c4a9b21f25d85b1
2017-03-24 20:47:41 +03:00
.. include:: inventories.inc
[placement] Add api-ref for GET RP inventory This provides simple documentation of the response body and path parameters when showing a single class of inventory for a resource provider. Change-Id: Ic562baa3e74445c8f6dbeb416c1ec183cc2ad14d
2017-04-10 12:34:00 +03:00
.. include:: inventory.inc
[placement] Add api-ref for aggregates This provides simple documentation of the path, request and response body parameters when listing and updating aggregates. Change-Id: Ife94d22e87a73fc26c4dcbda9545a9f59680f44f
2017-06-02 15:43:18 +03:00
.. include:: aggregates.inc
[placement] Add api-ref for traits This provides simple documentation of the path, request and response body parameters when listing, creating, updating and deleting traits. Change-Id: If377b725e0910de2e1768666184a0212c8c9fdbc
2017-06-14 14:41:33 +03:00
.. include:: traits.inc
[placement] Add api-ref for RP traits This provides simple documentation of the path, request and response body parameters when managing the association between traits and resource_providers. Change-Id: I2ef25313db89a2fd58d11dc023d2d9755d0a86ed
2017-06-14 14:43:25 +03:00
.. include:: resource_provider_traits.inc
[placement] Add api-ref for allocations This provides simple documentation of the path, request and response body parameters when listing, creating, updating and deleting allocations. Change-Id: I58e9dfcb62a2f485addeab98dcd835568ba792cf
2017-06-26 14:27:49 +03:00
.. include:: allocations.inc
[placement] Add api-ref for RP allocations This provides simple documentation of the path and response body parameters when listing resource provider allocations. Co-Authored-by: Andrey Volkov <avolkov@gmail.com> Change-Id: I40fcbc3077151227f33c6a021229b5c549889bbe
2017-06-26 15:30:07 +03:00
.. include:: resource_provider_allocations.inc
[placement] Add api-ref for usages Change-Id: I50954991f80725dc22be95eeecded2ee1e005e97
2017-06-29 14:55:16 +03:00
.. include:: usages.inc
[placement] Add api-ref for RP usages Add placement-api-ref for resource provider usages. Co-Authored-by: Andrey Volkov <avolkov@gmail.com> Change-Id: I6ba8765a427f654dafb32fc3fbf5492b0e1b426a
2017-03-23 18:00:29 +08:00
.. include:: resource_provider_usages.inc
[placement] Add api-ref for allocation_candidates Change-Id: Id89d7c16ca53938e2bc18e904e8d13477ceb15f7
2017-07-06 15:23:26 +03:00
.. include:: allocation_candidates.inc
Copy Permalink