From a34731dad1df53d9c5102161363a4bef46b62e52 Mon Sep 17 00:00:00 2001 From: Stephen Finucane Date: Thu, 28 Jun 2018 15:43:25 +0100 Subject: Convert 'placement_api_docs' into a Sphinx extension This ensures it will get run in the gate. Change-Id: I923c39d3115b595b8de94e85d2977eb7782d98e2 Signed-off-by: Stephen Finucane --- placement-api-ref/ext/__init__.py | 0 placement-api-ref/ext/validator.py | 68 ++++++++++++++++++++++++++++++++++++ placement-api-ref/source/conf.py | 5 +++ tools/placement_api_docs.py | 71 -------------------------------------- tox.ini | 2 -- 5 files changed, 73 insertions(+), 73 deletions(-) create mode 100644 placement-api-ref/ext/__init__.py create mode 100644 placement-api-ref/ext/validator.py delete mode 100644 tools/placement_api_docs.py diff --git a/placement-api-ref/ext/__init__.py b/placement-api-ref/ext/__init__.py new file mode 100644 index 0000000000..e69de29bb2 diff --git a/placement-api-ref/ext/validator.py b/placement-api-ref/ext/validator.py new file mode 100644 index 0000000000..44a4cef36a --- /dev/null +++ b/placement-api-ref/ext/validator.py @@ -0,0 +1,68 @@ +# 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 os + +from nova.api.openstack.placement import handler + +# A humane ordering of HTTP methods for sorted output. +ORDERED_METHODS = ['GET', 'POST', 'PUT', 'PATCH', 'DELETE'] +DEPRECATED_METHODS = [('POST', '/resource_providers/{uuid}/inventories')] + + +def _header_line(map_entry): + method, route = map_entry + line = '.. rest_method:: %s %s' % (method, route) + return line + + +def inspect_doc(app): + """Load up doc_files and see if any routes are missing. + + The routes are defined in handler.ROUTE_DECLARATIONS. + """ + doc_files = [os.path.join(app.srcdir, file) + for file in os.listdir(app.srcdir) if file.endswith(".inc")] + + 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: + if map_entry not in DEPRECATED_METHODS: + header_lines.append(_header_line(map_entry)) + + content_lines = [] + for doc_file in doc_files: + with open(doc_file) as doc_fh: + content_lines.extend(doc_fh.read().splitlines()) + + missing_lines = [] + for line in header_lines: + if line not in content_lines: + missing_lines.append(line) + + if missing_lines: + msg = ['Documentation likely missing for the following routes:', ''] + for line in missing_lines: + msg.append(line) + raise ValueError('\n'.join(msg)) + + +def setup(app): + app.connect('builder-inited', inspect_doc) diff --git a/placement-api-ref/source/conf.py b/placement-api-ref/source/conf.py index f52d3fdbd0..d4766be180 100644 --- a/placement-api-ref/source/conf.py +++ b/placement-api-ref/source/conf.py @@ -22,12 +22,17 @@ # All configuration values have a default; values that are commented out # serve to show the default. +import os +import sys + from nova.version import version_info +sys.path.insert(0, os.path.abspath('../')) extensions = [ 'openstackdocstheme', 'os_api_ref', + 'ext.validator', ] # -- General configuration ---------------------------------------------------- diff --git a/tools/placement_api_docs.py b/tools/placement_api_docs.py deleted file mode 100644 index bec5d25942..0000000000 --- a/tools/placement_api_docs.py +++ /dev/null @@ -1,71 +0,0 @@ -# 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 os -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'] -DEPRECATED_METHODS = [('POST', '/resource_providers/{uuid}/inventories')] - - -def _header_line(map_entry): - method, route = map_entry - line = '.. rest_method:: %s %s' % (method, route) - return line - - -def inspect_doc(doc_files): - """Load up doc_files 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: - if map_entry not in DEPRECATED_METHODS: - header_lines.append(_header_line(map_entry)) - - content_lines = [] - for doc_file in doc_files: - with open(doc_file) as doc_fh: - content_lines.extend(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__': - path = sys.argv[1] - doc_files = [os.path.join(path, file) - for file in os.listdir(path) if file.endswith(".inc")] - sys.exit(inspect_doc(doc_files)) diff --git a/tox.ini b/tox.ini index a6e5828644..e1c0823a5c 100644 --- a/tox.ini +++ b/tox.ini @@ -182,8 +182,6 @@ description = Generate the Placement API ref. Called from CI scripts to test and publish to developer.openstack.org. deps = {[testenv:docs]deps} commands = - # Check that all placement api routes are in the documentation - python tools/placement_api_docs.py placement-api-ref/source/ rm -rf placement-api-ref/build sphinx-build -W -b html -d placement-api-ref/build/doctrees placement-api-ref/source placement-api-ref/build/html -- cgit v1.2.1