From cdee2719f7402b705dd4dbe55282e2d1672b5329 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Vincent=20Fran=C3=A7oise?= Date: Mon, 17 Oct 2016 17:21:57 +0200 Subject: [PATCH] Added notifications documentation page In this changeset, I added a new Sphinx directive (from Nova) that allows us to automatically display notification samples for of all the upcoming notifications in Watcher. Partially Implements: blueprint watcher-notifications-ovo Change-Id: Id7d819ee21db6dc616c78faea483b883f77e3bd6 --- doc/ext/versioned_notifications.py | 133 +++++++++++++++++++++ doc/source/conf.py | 3 +- doc/source/dev/notifications.rst | 13 ++ doc/source/index.rst | 1 + watcher/objects/notifications/exception.py | 1 + 5 files changed, 150 insertions(+), 1 deletion(-) create mode 100644 doc/ext/versioned_notifications.py create mode 100644 doc/source/dev/notifications.rst diff --git a/doc/ext/versioned_notifications.py b/doc/ext/versioned_notifications.py new file mode 100644 index 000000000..f3b2d8582 --- /dev/null +++ b/doc/ext/versioned_notifications.py @@ -0,0 +1,133 @@ +# 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. + +""" +This provides a sphinx extension able to list the implemented versioned +notifications into the developer documentation. + +It is used via a single directive in the .rst file + + .. versioned_notifications:: + +""" + +from sphinx.util.compat import Directive +from docutils import nodes + +from watcher.objects.notifications import base as notification +from watcher.objects import base + + +class VersionedNotificationDirective(Directive): + + SAMPLE_ROOT = 'doc/notification_samples/' + TOGGLE_SCRIPT = """ + +""" + + def run(self): + notifications = self._collect_notifications() + return self._build_markup(notifications) + + def _collect_notifications(self): + base.WatcherObjectRegistry.register_notification_objects() + notifications = [] + ovos = base.WatcherObjectRegistry.obj_classes() + for name, cls in ovos.items(): + cls = cls[0] + if (issubclass(cls, notification.NotificationBase) and + cls != notification.NotificationBase): + + payload_name = cls.fields['payload'].objname + payload_cls = ovos[payload_name][0] + for sample in cls.samples: + notifications.append((cls.__name__, + payload_cls.__name__, + sample)) + return sorted(notifications) + + def _build_markup(self, notifications): + content = [] + cols = ['Event type', 'Notification class', 'Payload class', 'Sample'] + table = nodes.table() + content.append(table) + group = nodes.tgroup(cols=len(cols)) + table.append(group) + + head = nodes.thead() + group.append(head) + + for _ in cols: + group.append(nodes.colspec(colwidth=1)) + + body = nodes.tbody() + group.append(body) + + # fill the table header + row = nodes.row() + body.append(row) + for col_name in cols: + col = nodes.entry() + row.append(col) + text = nodes.strong(text=col_name) + col.append(text) + + # fill the table content, one notification per row + 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) + col.append(text) + + col = nodes.entry() + row.append(col) + text = nodes.literal(text=payload) + col.append(text) + + col = nodes.entry() + row.append(col) + + 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 += ("" % event_type) + html_str += ("
%s
" + % (event_type, sample_content)) + + raw = nodes.raw('', html_str, format="html") + col.append(raw) + + return content + + +def setup(app): + app.add_directive('versioned_notifications', + VersionedNotificationDirective) diff --git a/doc/source/conf.py b/doc/source/conf.py index 33fb6937b..0cc656726 100755 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -12,8 +12,8 @@ # See the License for the specific language governing permissions and # limitations under the License. -import sys import os +import sys from watcher import version as watcher_version from watcher import objects @@ -41,6 +41,7 @@ extensions = [ 'stevedore.sphinxext', 'wsmeext.sphinxext', 'ext.term', + 'ext.versioned_notifications', ] wsme_protocols = ['restjson'] diff --git a/doc/source/dev/notifications.rst b/doc/source/dev/notifications.rst new file mode 100644 index 000000000..6ee733938 --- /dev/null +++ b/doc/source/dev/notifications.rst @@ -0,0 +1,13 @@ +.. + Except where otherwise noted, this document is licensed under Creative + Commons Attribution 3.0 License. You can view the license at: + + https://creativecommons.org/licenses/by/3.0/ + +.. _watcher_notifications: + +======================== +Notifications in Watcher +======================== + +.. versioned_notifications:: diff --git a/doc/source/index.rst b/doc/source/index.rst index 8b665fac3..2c77b4f9a 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -56,6 +56,7 @@ Getting Started dev/devstack deploy/configuration deploy/conf-files + dev/notifications dev/testing dev/rally_link diff --git a/watcher/objects/notifications/exception.py b/watcher/objects/notifications/exception.py index 4674b420c..afe954819 100644 --- a/watcher/objects/notifications/exception.py +++ b/watcher/objects/notifications/exception.py @@ -43,6 +43,7 @@ class ExceptionPayload(notificationbase.NotificationPayloadBase): exception_message=six.text_type(fault)) +@notificationbase.notification_sample('infra-optim-exception.json') @base.WatcherObjectRegistry.register_notification class ExceptionNotification(notificationbase.NotificationBase): # Version 1.0: Initial version