fix microversion parsing in parameters.yaml

This fixes the parsing of min_version and max_version in
parameters.yaml by treating things that look like floats as
strings. Otherwise 2.20 ends up folding to 2.2, which is definitely
not intentional.

This also adds a set of tests for microversion class setting in both
parameters in tables as well as in the method itself.

Change-Id: If2713fc4038e69d113cdaa7db0231a1d03f6223b

os_api_ref/__init__.py

@@ -76,6 +76,12 @@ def construct_mapping(loader, node):
     OrderedLoader.add_constructor(
         yaml.resolver.BaseResolver.DEFAULT_MAPPING_TAG,
         construct_mapping)
+    # for parameters.yaml we treat numbers (especially version
+    # numbers) as strings. So that microversion specification of 2.20
+    # and 2.2 don't get confused.
+    OrderedLoader.add_constructor(
+        u'tag:yaml.org,2002:float',
+        yaml.constructor.SafeConstructor.construct_yaml_str)
 
     return yaml.load(stream, OrderedLoader)
 

os_api_ref/tests/examples/microversions/conf.py

@@ -0,0 +1,29 @@
+# -*- 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.
+
+# -- 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.
+
+extensions = [
+    'os_api_ref',
+    'oslosphinx',
+]
+
+# The suffix of source filenames.
+source_suffix = '.rst'
+
+# The master toctree document.
+master_doc = 'index'

os_api_ref/tests/examples/microversions/index.rst

@@ -0,0 +1,23 @@
+.. rest_expand_all::
+
+I am text, hear me roar!
+
+==============
+ List Servers
+==============
+
+.. rest_method:: GET /servers
+
+.. rest_parameters:: parameters.yaml
+
+   - name: name
+   - name2: name2
+   - name3: name3
+
+===========
+ List Tags
+===========
+
+.. rest_method:: GET /tags
+   min_version: 2.17
+   max_version: 2.19

os_api_ref/tests/examples/microversions/parameters.yaml

@@ -0,0 +1,20 @@
+name:
+  in: body
+  required: true
+  type: string
+  description: |
+    The name of things
+name2:
+  in: body
+  required: true
+  type: string
+  description: |
+    The name of things
+  min_version: 2.11
+name3:
+  in: body
+  required: true
+  type: string
+  description: |
+    The name of things
+  max_version: 2.20

os_api_ref/tests/test_microversions.py

@@ -0,0 +1,99 @@
+# -*- 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.
+
+"""
+test_os_api_ref
+----------------------------------
+
+Tests for `os_api_ref` module.
+"""
+
+from bs4 import BeautifulSoup
+from sphinx_testing import with_app
+
+from os_api_ref.tests import base
+
+
+class TestMicroversions(base.TestCase):
+    """Test basic rendering.
+
+    This can be used to test that basic rendering works for these
+    examples, so if someone breaks something we know.
+    """
+
+    @with_app(buildername='html', srcdir=base.example_dir('microversions'),
+              copy_srcdir_to_tmpdir=True)
+    def setUp(self, app, status, warning):
+        super(TestMicroversions, self).setUp()
+        self.app = app
+        self.app.build()
+        self.status = status.getvalue()
+        self.warning = warning.getvalue()
+        self.html = (app.outdir / 'index.html').read_text()
+        self.soup = BeautifulSoup(self.html, 'html.parser')
+        self.content = str(self.soup)
+
+    def test_rest_method(self):
+        """Do we get an out of order naming warning."""
+        content = self.soup.find_all(class_='rp_min_ver_2_17')
+        self.assertIn(
+            '<div class="row operation-grp rp_min_ver_2_17 rp_max_ver_2_19 ">',
+            str(content[0]))
+        content = self.soup.find_all(class_='rp_max_ver_2_19')
+        self.assertIn(
+            '<div class="row operation-grp rp_min_ver_2_17 rp_max_ver_2_19 ">',
+            str(content[0]))
+
+    def test_parameters_table(self):
+
+        table = """<div class="api-detail collapse section" id="list-servers-detail">
+<table border="1" class="docutils">
+<colgroup>
+<col width="20%"></col>
+<col width="10%"></col>
+<col width="10%"></col>
+<col width="60%"></col>
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">Name</th>
+<th class="head">In</th>
+<th class="head">Type</th>
+<th class="head">Description</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>name</td>
+<td>body</td>
+<td>string</td>
+<td>The name of things</td>
+</tr>
+<tr class="rp_min_ver_2_11 row-odd"><td>name2</td>
+<td>body</td>
+<td>string</td>
+<td><p class="first">The name of things</p>
+<p class="last"><strong>New in version 2.11</strong></p>
+</td>
+</tr>
+<tr class="rp_max_ver_2_20 row-even"><td>name3</td>
+<td>body</td>
+<td>string</td>
+<td><p class="first">The name of things</p>
+<p class="last"><strong>Deprecated in version 2.20</strong></p>
+</td>
+</tr>
+</tbody>
+</table>
+</div>
+"""
+        self.assertIn(table, self.content)