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

.gitignore

@@ -32,6 +32,7 @@ doc/source/api/*
 doc/build/*
 api-guide/build/*
 api-ref/build/*
+placement-api-ref/build/*
 etc/nova/nova.conf.sample
 etc/nova/policy.yaml.sample
 etc/nova/policy.yaml.merged

placement-api-ref/source/conf.py

@@ -0,0 +1,231 @@
+# -*- coding: utf-8 -*-
+#
+# 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.
+#
+# placement-api-ref documentation build configuration file, created by
+# sphinx-quickstart on Sat May  1 15:17:47 2010.
+#
+# This file is execfile()d with the current directory set to
+# its containing dir.
+#
+# Note that not all possible configuration values are present in this
+# autogenerated file.
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+import os
+import subprocess
+import sys
+import warnings
+
+import openstackdocstheme
+
+extensions = [
+    'os_api_ref',
+]
+
+
+html_theme = 'openstackdocs'
+html_theme_path = [openstackdocstheme.get_html_theme_path()]
+html_theme_options = {
+    "sidebar_mode": "toc",
+}
+html_context = {'bug_project': 'nova', 'bug_tag': 'placement-api-ref'}
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+sys.path.insert(0, os.path.abspath('../../'))
+sys.path.insert(0, os.path.abspath('../'))
+sys.path.insert(0, os.path.abspath('./'))
+
+# -- General configuration ----------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
+
+# The suffix of source filenames.
+source_suffix = '.rst'
+
+# The encoding of source files.
+#
+# source_encoding = 'utf-8'
+
+# The master toctree document.
+master_doc = 'index'
+
+# General information about the project.
+project = u'Placement API Reference'
+copyright = u'2010-present, OpenStack Foundation'
+
+# The version info for the project you're documenting, acts as replacement for
+# |version| and |release|, also used in various other places throughout the
+# built documents.
+#
+from nova.version import version_info
+# The full version, including alpha/beta/rc tags.
+release = version_info.release_string()
+# The short X.Y version.
+version = version_info.version_string()
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#
+# language = None
+
+# There are two options for replacing |today|: either, you set today to some
+# non-false value, then it is used:
+# today = ''
+# Else, today_fmt is used as the format for a strftime call.
+# today_fmt = '%B %d, %Y'
+
+# The reST default role (used for this markup: `text`) to use
+# for all documents.
+# default_role = None
+
+# If true, '()' will be appended to :func: etc. cross-reference text.
+# add_function_parentheses = True
+
+# If true, the current module name will be prepended to all description
+# unit titles (such as .. function::).
+add_module_names = False
+
+# If true, sectionauthor and moduleauthor directives will be shown in the
+# output. They are ignored by default.
+show_authors = False
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+# -- Options for man page output ----------------------------------------------
+
+# Grouping the document tree for man pages.
+# List of tuples 'sourcefile', 'target', u'title', u'Authors name', 'manual'
+
+
+# -- Options for HTML output --------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  Major themes that come with
+# Sphinx are currently 'default' and 'sphinxdoc'.
+# html_theme_path = ["."]
+# html_theme = '_theme'
+
+# Theme options are theme-specific and customize the look and feel of a theme
+# further.  For a list of options available for each theme, see the
+# documentation.
+# html_theme_options = {}
+
+# Add any paths that contain custom themes here, relative to this directory.
+# html_theme_path = []
+
+# The name for this set of Sphinx documents.  If None, it defaults to
+# "<project> v<release> documentation".
+# html_title = None
+
+# A shorter title for the navigation bar.  Default is the same as html_title.
+# html_short_title = None
+
+# The name of an image file (relative to this directory) to place at the top
+# of the sidebar.
+# html_logo = None
+
+# The name of an image file (within the static path) to use as favicon of the
+# docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
+# pixels large.
+# html_favicon = None
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+# html_static_path = ['_static']
+
+# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
+# using the given strftime format.
+# html_last_updated_fmt = '%b %d, %Y'
+git_cmd = ["git", "log", "--pretty=format:'%ad, commit %h'", "--date=local",
+    "-n1"]
+try:
+    html_last_updated_fmt = subprocess.Popen(
+        git_cmd, stdout=subprocess.PIPE).communicate()[0].decode()
+except Exception:
+    warnings.warn('Cannot get last updated time from git repository. '
+                  'Not setting "html_last_updated_fmt".')
+
+# If true, SmartyPants will be used to convert quotes and dashes to
+# typographically correct entities.
+# html_use_smartypants = True
+
+# Custom sidebar templates, maps document names to template names.
+# html_sidebars = {}
+
+# Additional templates that should be rendered to pages, maps page names to
+# template names.
+# html_additional_pages = {}
+
+# If false, no module index is generated.
+# html_use_modindex = True
+
+# If false, no index is generated.
+# html_use_index = True
+
+# If true, the index is split into individual pages for each letter.
+# html_split_index = False
+
+# If true, links to the reST sources are added to the pages.
+# html_show_sourcelink = True
+
+# If true, an OpenSearch description file will be output, and all pages will
+# contain a <link> tag referring to it.  The value of this option must be the
+# base URL from which the finished HTML is served.
+# html_use_opensearch = ''
+
+# If nonempty, this is the file name suffix for HTML files (e.g. ".xhtml").
+# html_file_suffix = ''
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'placementdoc'
+
+
+# -- Options for LaTeX output -------------------------------------------------
+
+# The paper size ('letter' or 'a4').
+# latex_paper_size = 'letter'
+
+# The font size ('10pt', '11pt' or '12pt').
+# latex_font_size = '10pt'
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title, author, documentclass
+# [howto/manual]).
+latex_documents = [
+    ('index', 'Placement.tex', u'OpenStack Placement API Documentation',
+     u'OpenStack Foundation', 'manual'),
+]
+
+# The name of an image file (relative to this directory) to place at the top of
+# the title page.
+# latex_logo = None
+
+# For "manual" documents, if this is true, then toplevel headings are parts,
+# not chapters.
+# latex_use_parts = False
+
+# Additional stuff for the LaTeX preamble.
+# latex_preamble = ''
+
+# Documents to append as an appendix to all manuals.
+# latex_appendices = []
+
+# If false, no module index is generated.
+# latex_use_modindex = True

placement-api-ref/source/get-root.json

@@ -0,0 +1,9 @@
+{
+    "versions" : [
+        {
+            "min_version" : "1.0",
+            "id" : "v1.0",
+            "max_version" : "1.2"
+        }
+    ]
+}

placement-api-ref/source/index.rst

@@ -0,0 +1,46 @@
+:tocdepth: 2
+
+===============
+ Placement API
+===============
+
+.. TODO(cdent) this is a big pile of todo
+
+This is a reference for the Openstack Placement API. To learn more about
+Openstack Placement API concepts, please refer to the
+`Placement Introduction <http://docs.openstack.org/developer/nova/placement.html>`_.
+
+.. rest_expand_all::
+
+========
+Versions
+========
+
+List Versions
+=============
+
+.. rest_method:: GET /
+
+Fetch information about all known major versions of the placement API,
+including information about the minimum and maximum microversions.
+
+.. note:: At this time there is only one major version of the placement API:
+          version 1.0.
+
+Normal Response Codes: 200
+
+Response
+--------
+
+.. rest_parameters:: parameters.yaml
+
+  - versions: versions
+  - id: version_id
+  - min_version: version_min
+  - max_version: version_max
+
+Response Example
+----------------
+
+.. literalinclude:: get-root.json
+   :language: javascript

placement-api-ref/source/parameters.yaml

@@ -0,0 +1,24 @@
+version_id:
+  type: string
+  in: body
+  required: true
+  description: >
+    A common name for the version being described. Informative only.
+version_max:
+  type: string
+  in: body
+  required: true
+  description: >
+    The maximum microversion that is supported.
+version_min:
+  type: string
+  in: body
+  required: true
+  description: >
+    The minimum microversion that is supported.
+versions:
+  type: array
+  in: body
+  required: true
+  description: >
+    A list of version objects that describe the API versions available.

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))

tox.ini

@@ -108,7 +108,7 @@ commands = {posargs}
 # with python 3.x
 basepython = python2.7
 commands =
-  rm -rf doc/source/api doc/build api-guide/build api-ref/build
+  rm -rf doc/source/api doc/build api-guide/build api-ref/build placement-api-ref/build
   python setup.py build_sphinx
   # Check that all JSON files don't have \r\n in line.
   bash -c "! find doc/ -type f -name *.json | xargs grep -U -n $'\r'"
@@ -120,6 +120,7 @@ commands =
   oslopolicy-policy-generator --namespace nova --output-file etc/nova/policy.yaml.merged
   sphinx-build -W -b html api-guide/source api-guide/build/html
   sphinx-build -W -b html api-ref/source api-ref/build/html
+  sphinx-build -W -b html placement-api-ref/source placement-api-ref/build/html
 
 [testenv:api-guide]
 # This environment is called from CI scripts to test and publish
@@ -134,6 +135,18 @@ commands =
   rm -rf api-ref/build
   sphinx-build -W -b html -d api-ref/build/doctrees api-ref/source api-ref/build/html
 
+[testenv:placement-api-ref]
+# This environment is called from CI scripts to test and publish
+# the Placement API Ref to developer.openstack.org.
+commands =
+  # Check that all placement api routes are in the documentation
+  # TODO(cdent): Get rid of the leading '-' after all the existing
+  # routes have been documented. It causes the non-zero exit code to
+  # ignored.
+  - python tools/placement_api_docs.py placement-api-ref/source/index.rst
+  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
+
 [testenv:bandit]
 # NOTE(browne): This is required for the integration test job of the bandit
 # project. Please do not remove.