openstack
/
os-api-ref
Code Issues Proposed changes

add experimental microversion selector 

This adds experimental support for a microversion selector. The
interface for this may well change over time. To currently use this we
need 2 values in the sphinx conf.py to specify min and max
microversions. If you don't have those added, nothing is changed in
the UI.

Use at your own risk. However it's much easier to get feedback if we
have this in the package.

Change-Id: Iaf7e117ea5792bb3b60c1fd0ae416b241ab89d65
This commit is contained in:
Sean Dague 2016-05-27 10:57:13 -04:00
parent f2f0511d3e
commit f93c467e9a
5 changed files with 137 additions and 6 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

43
os_api_ref/__init__.py
View File

@ -123,7 +123,22 @@ class RestExpandAllDirective(Directive):
has_content = True
def run(self):
return [rest_expand_all()]
app = self.state.document.settings.env.app
node = rest_expand_all()
max_ver = app.config.os_api_ref_max_microversion
min_ver = app.config.os_api_ref_min_microversion
node['major'] = None
try:
if max_ver.split('.')[0] == min_ver.split('.')[0]:
node['max_ver'] = int(max_ver.split('.')[1])
node['min_ver'] = int(min_ver.split('.')[1])
node['major'] = int(max_ver.split('.')[0])
except ValueError:
# TODO(sdague): warn that we're ignoring this all
pass
except IndexError:
pass
return [node]
class RestMethodDirective(Directive):
@ -457,8 +472,9 @@ def rest_method_html(self, node):
def rest_expand_all_html(self, node):
tmpl = """
<div>
<div class=col-md-11></div>
<div class="row">
%(extra_js)s
<div class=col-md-11>%(selector)s</div>
<div class=col-md-1>
<button id="expand-all"
data-toggle="collapse"
@ -467,6 +483,24 @@ def rest_expand_all_html(self, node):
</div>
</div>"""
if node['major']:
selector = """
<div class="btn-group" role="group" aria-label="...">
<button type="button"
class="btn btn-default mv_selector active">All</button>\n"""
for x in range(node['min_ver'], node['max_ver'] + 1):
selector += ('<button type="button" class="btn btn-default '
'mv_selector">%d.%d</button>\n' % (node['major'], x))
selector += "</div>"
node['selector'] = selector
node['extra_js'] = ("<script>os_max_mv = %d; "
"os_min_mv = %d;</script>") % (
node['max_ver'],
node['min_ver'])
else:
node['selector'] = ""
node['extra_js'] = ""
self.body.append(tmpl % node)
raise nodes.SkipNode
@ -525,6 +559,9 @@ def add_assets(app):
def setup(app):
# Add some config options around microversions
app.add_config_value('os_api_ref_max_microversion', '', 'env')
app.add_config_value('os_api_ref_min_microversion', '', 'env')
# TODO(sdague): if someone wants to support latex/pdf, or man page
# generation using these stanzas, here is where you'd need to
# specify content specific renderers.

12
os_api_ref/assets/api-site.css
View File

@ -128,3 +128,15 @@ span.path_parameter {
background-color: #f9f2f4;
border-radius: 4px;
}
/* for microversion selector */
.mv_selector {
font-size: 0.8em;
padding: 0.3em;
}
.mv_selector.active {
color: #fff;
background-color: #31b0d5;
border-color: #269abc;
}

37
os_api_ref/assets/api-site.js
View File

@ -1,3 +1,6 @@
var os_min_mv = 1;
var os_max_mv = 1;
(function() {
// the list of expanded element ids
var expanded = [];
@ -72,6 +75,17 @@
$(document.body).scrollTop($(window.location.hash).offset().top);
}
// Wire up microversion selector
$('.mv_selector').on('click', function(e) {
var version = e.currentTarget.innerHTML;
// flip what is active
$(this).addClass('active').siblings().removeClass('active');
if (version == "All") {
reset_microversion();
} else {
set_microversion(version);
}
});
});
/**
* Helper function for setting the text, styles for expandos
@ -93,6 +107,7 @@
}
}
// Generically update the query string for a url. Credit to
// http://stackoverflow.com/questions/5999118/add-or-update-query-string-parameter
// for making this properly generic.
@ -126,4 +141,26 @@
}
}
// Set the Y value of the microversion to turn on / off visibility
// of components.
function set_microversion(number) {
var major = number.split(".")[0];
var micro = number.split(".")[1];
for (var i = os_min_mv; i <= os_max_mv; i++) {
var max_class = ".rp_max_ver_" + major + "_" + i;
var min_class = ".rp_min_ver_" + major + "_" + i;
if (i < micro) {
$(max_class).hide(400);
$(min_class).show(400);
} else if (i >= micro) {
$(min_class).hide(400);
$(max_class).show(400);
}
}
}
function reset_microversion() {
$('[class^=rp_min_ver]').show(400);
$('[class^=rp_max_ver]').show(400);
}
})();

3
os_api_ref/tests/examples/microversions/conf.py
View File

@ -27,3 +27,6 @@ source_suffix = '.rst'
# The master toctree document.
master_doc = 'index'
os_api_ref_min_microversion = '2.1'
os_api_ref_max_microversion = '2.30'

48
os_api_ref/tests/test_microversions.py
View File

@ -45,7 +45,7 @@ class TestMicroversions(base.TestCase):
self.content = str(self.soup)
def test_rest_method(self):
"""Do we get an out of order naming warning."""
"""Test that min / max mv css class attributes are set"""
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 ">',
@ -56,7 +56,7 @@ class TestMicroversions(base.TestCase):
str(content[0]))
def test_parameters_table(self):
"""Test that min / max mv css class attributes are set in params"""
table = """<div class="api-detail collapse section" id="list-servers-detail">
<table border="1" class="docutils">
<colgroup>
@ -95,5 +95,47 @@ class TestMicroversions(base.TestCase):
</tbody>
</table>
</div>
"""
""" # noqa
self.assertIn(table, self.content)
def test_mv_selector(self):
button_selectors = \
"""<div aria-label="..." class="btn-group" role="group">
<button class="btn btn-default mv_selector active" type="button">All</button>
<button class="btn btn-default mv_selector" type="button">2.1</button>
<button class="btn btn-default mv_selector" type="button">2.2</button>
<button class="btn btn-default mv_selector" type="button">2.3</button>
<button class="btn btn-default mv_selector" type="button">2.4</button>
<button class="btn btn-default mv_selector" type="button">2.5</button>
<button class="btn btn-default mv_selector" type="button">2.6</button>
<button class="btn btn-default mv_selector" type="button">2.7</button>
<button class="btn btn-default mv_selector" type="button">2.8</button>
<button class="btn btn-default mv_selector" type="button">2.9</button>
<button class="btn btn-default mv_selector" type="button">2.10</button>
<button class="btn btn-default mv_selector" type="button">2.11</button>
<button class="btn btn-default mv_selector" type="button">2.12</button>
<button class="btn btn-default mv_selector" type="button">2.13</button>
<button class="btn btn-default mv_selector" type="button">2.14</button>
<button class="btn btn-default mv_selector" type="button">2.15</button>
<button class="btn btn-default mv_selector" type="button">2.16</button>
<button class="btn btn-default mv_selector" type="button">2.17</button>
<button class="btn btn-default mv_selector" type="button">2.18</button>
<button class="btn btn-default mv_selector" type="button">2.19</button>
<button class="btn btn-default mv_selector" type="button">2.20</button>
<button class="btn btn-default mv_selector" type="button">2.21</button>
<button class="btn btn-default mv_selector" type="button">2.22</button>
<button class="btn btn-default mv_selector" type="button">2.23</button>
<button class="btn btn-default mv_selector" type="button">2.24</button>
<button class="btn btn-default mv_selector" type="button">2.25</button>
<button class="btn btn-default mv_selector" type="button">2.26</button>
<button class="btn btn-default mv_selector" type="button">2.27</button>
<button class="btn btn-default mv_selector" type="button">2.28</button>
<button class="btn btn-default mv_selector" type="button">2.29</button>
<button class="btn btn-default mv_selector" type="button">2.30</button>
</div>"""
self.assertIn(button_selectors, self.content)
def test_js_declares(self):
self.assertIn("os_max_mv = 30;", self.content)
self.assertIn("os_min_mv = 1;", self.content)