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

1 files changed, 64 insertions, 0 deletions

diff --git a/tools/placement_api_docs.py b/tools/placement_api_docs.py
new file mode 100644
index 0000000000..652800cf8d
--- /dev/null
+++ b/tools/placement_api_docs.py
@@ -0,0 +1,64 @@
+#    Licensed under the Apache License, Version 2.0 (the "License"); you may
+#    not use this file except in compliance with the License. You may obtain
+#    a copy of the License at
+#
+#         http://www.apache.org/licenses/LICENSE-2.0
+#
+#    Unless required by applicable law or agreed to in writing, software
+#    distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+#    WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+#    License for the specific language governing permissions and limitations
+#    under the License.
+"""Test to see if docs exists for routes and methods in the placement API."""
+
+import sys
+
+from nova.api.openstack.placement import handler
+
+# A humane ordering of HTTP methods for sorted output.
+ORDERED_METHODS = ['GET', 'POST', 'PUT', 'PATCH', 'DELETE']
+
+
+def _header_line(map_entry):
+    method, route = map_entry
+    line = '.. rest_method:: %s %s' % (method, route)
+    return line
+
+
+def inspect_doc(doc_file):
+    """Load up doc_file and see if any routes are missing.
+
+    The routes are defined in handler.ROUTE_DECLARATIONS.
+    """
+    routes = []
+    for route in sorted(handler.ROUTE_DECLARATIONS, key=len):
+        # Skip over the '' route.
+        if route:
+            for method in ORDERED_METHODS:
+                if method in handler.ROUTE_DECLARATIONS[route]:
+                    routes.append((method, route))
+
+    header_lines = []
+    for map_entry in routes:
+        header_lines.append(_header_line(map_entry))
+
+    with open(doc_file) as doc_fh:
+        content_lines = doc_fh.read().splitlines()
+
+    missing_lines = []
+    for line in header_lines:
+        if line not in content_lines:
+            missing_lines.append(line)
+
+    if missing_lines:
+        print('Documentation likely missing for the following routes:')
+        for line in missing_lines:
+            print(line)
+        return 1
+
+    return 0
+
+
+if __name__ == '__main__':
+    doc_file = sys.argv[1]
+    sys.exit(inspect_doc(doc_file))