openstack/nova
Code Issues Proposed changes

Enhance notification doc generation with samples

Browse Source 
Until now the notification devref only contained a link to the sample file
and that link did only exist after the sample file was merged.
This is suboptimal as the locally generated doc might be incomplete.

This patch changes the doc to contain the content of the sample file.

Change-Id: I4343a2feb13de8b614e8d42d5f1db14102ab492e
This commit is contained in:
Balazs Gibizer 2016-07-19 10:24:03 +02:00
parent ad4a6e9502
commit e5798f9f9d
1 changed files with 36 additions and 17 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

53
doc/ext/versioned_notifications.py
View File

@ -27,14 +27,19 @@ from nova.notifications.objects import base as notification
from nova.objects import base
def full_name(cls):
return cls.__module__ + '.' + cls.__name__
class VersionedNotificationDirective(Directive):
LINK_PREFIX = 'https://git.openstack.org/cgit/openstack/nova/plain/'
SAMPLE_ROOT = 'doc/notification_samples/'
TOGGLE_SCRIPT = """
<script>
jQuery(document).ready(function(){
jQuery('#%s-div').toggle('show');
jQuery('#%s-hideshow').on('click', function(event) {
jQuery('#%s-div').toggle('show');
});
});
</script>
"""
def run(self):
notifications = self._collect_notifications()
@ -52,14 +57,14 @@ class VersionedNotificationDirective(Directive):
payload_name = cls.fields['payload'].objname
payload_cls = ovos[payload_name][0]
for sample in cls.samples:
notifications.append((full_name(cls),
full_name(payload_cls),
notifications.append((cls.__name__,
payload_cls.__name__,
sample))
return notifications
return sorted(notifications)
def _build_markup(self, notifications):
content = []
cols = ['Notification class', 'Payload class', 'Sample file link']
cols = ['Event type', 'Notification class', 'Payload class', 'Sample']
table = nodes.table()
content.append(table)
group = nodes.tgroup(cols=len(cols))
@ -68,7 +73,7 @@ class VersionedNotificationDirective(Directive):
head = nodes.thead()
group.append(head)
for i in range(len(cols)):
for _ in cols:
group.append(nodes.colspec(colwidth=1))
body = nodes.tbody()
@ -84,9 +89,16 @@ class VersionedNotificationDirective(Directive):
col.append(text)
# fill the table content, one notification per row
for name, payload, sample in notifications:
for name, payload, sample_file in notifications:
event_type = sample_file[0: -5].replace('-', '.')
row = nodes.row()
body.append(row)
col = nodes.entry()
row.append(col)
text = nodes.literal(text=event_type)
col.append(text)
col = nodes.entry()
row.append(col)
text = nodes.literal(text=name)
@ -99,12 +111,19 @@ class VersionedNotificationDirective(Directive):
col = nodes.entry()
row.append(col)
ref = nodes.reference(refuri=self.LINK_PREFIX +
self.SAMPLE_ROOT + sample)
txt = nodes.inline()
col.append(txt)
txt.append(ref)
ref.append(nodes.literal(text=sample))
with open(self.SAMPLE_ROOT + sample_file, 'r') as f:
sample_content = f.read()
event_type = sample_file[0: -5]
html_str = self.TOGGLE_SCRIPT % ((event_type, ) * 3)
html_str += ("<input type='button' id='%s-hideshow' "
"value='hide/show sample'>" % event_type)
html_str += ("<div id='%s-div'><pre>%s</pre></div>"
% (event_type, sample_content))
raw = nodes.raw('', html_str, format="html")
col.append(raw)
return content