From 952a8f2fafe1beb54da58b37524557f2ea9e7f43 Mon Sep 17 00:00:00 2001 From: Fabio Manganiello Date: Mon, 30 Dec 2019 18:50:01 +0100 Subject: [PATCH] Added generation for events docs --- docs/source/events.rst | 12 +++- docs/source/platypush/events/.rst | 5 ++ docs/source/platypush/events/bluetooth.rst | 5 ++ docs/source/platypush/events/distance.rst | 5 ++ .../source/platypush/events/google.pubsub.rst | 5 ++ docs/source/platypush/events/google.rst | 5 ++ docs/source/platypush/events/gps.rst | 5 ++ .../platypush/events/http.ota.booking.rst | 5 ++ docs/source/platypush/events/mqtt.rst | 5 ++ docs/source/platypush/events/todoist.rst | 5 ++ docs/source/platypush/events/zeroborg.rst | 5 ++ generate_missing_docs.py | 37 ++++++++++++ platypush/plugins/inspect.py | 58 +++++++++++++++++++ 13 files changed, 156 insertions(+), 1 deletion(-) create mode 100644 docs/source/platypush/events/.rst create mode 100644 docs/source/platypush/events/bluetooth.rst create mode 100644 docs/source/platypush/events/distance.rst create mode 100644 docs/source/platypush/events/google.pubsub.rst create mode 100644 docs/source/platypush/events/google.rst create mode 100644 docs/source/platypush/events/gps.rst create mode 100644 docs/source/platypush/events/http.ota.booking.rst create mode 100644 docs/source/platypush/events/mqtt.rst create mode 100644 docs/source/platypush/events/todoist.rst create mode 100644 docs/source/platypush/events/zeroborg.rst diff --git a/docs/source/events.rst b/docs/source/events.rst index a1125b10..d6d58201 100644 --- a/docs/source/events.rst +++ b/docs/source/events.rst @@ -1,3 +1,4 @@ + Events ====== @@ -5,21 +6,29 @@ Events :maxdepth: 2 :caption: Events: + platypush/events/.rst platypush/events/adafruit.rst platypush/events/application.rst platypush/events/assistant.rst + platypush/events/bluetooth.rst platypush/events/button.flic.rst platypush/events/camera.rst + platypush/events/distance.rst platypush/events/geo.rst + platypush/events/google.rst platypush/events/google.fit.rst + platypush/events/google.pubsub.rst + platypush/events/gps.rst platypush/events/http.rst platypush/events/http.hook.rst + platypush/events/http.ota.booking.rst platypush/events/http.rss.rst platypush/events/joystick.rst platypush/events/kafka.rst platypush/events/light.rst platypush/events/media.rst platypush/events/midi.rst + platypush/events/mqtt.rst platypush/events/music.rst platypush/events/music.snapcast.rst platypush/events/nfc.rst @@ -33,10 +42,11 @@ Events platypush/events/sensor.light.rst platypush/events/serial.rst platypush/events/sound.rst + platypush/events/todoist.rst platypush/events/torrent.rst platypush/events/video.rst platypush/events/weather.rst platypush/events/web.rst platypush/events/web.widget.rst platypush/events/wiimote.rst - + platypush/events/zeroborg.rst diff --git a/docs/source/platypush/events/.rst b/docs/source/platypush/events/.rst new file mode 100644 index 00000000..abf3b8ad --- /dev/null +++ b/docs/source/platypush/events/.rst @@ -0,0 +1,5 @@ +``platypush.message.event`` +=========================== + +.. automodule:: platypush.message.event + :members: diff --git a/docs/source/platypush/events/bluetooth.rst b/docs/source/platypush/events/bluetooth.rst new file mode 100644 index 00000000..ef2860d8 --- /dev/null +++ b/docs/source/platypush/events/bluetooth.rst @@ -0,0 +1,5 @@ +``platypush.message.event.bluetooth`` +===================================== + +.. automodule:: platypush.message.event.bluetooth + :members: diff --git a/docs/source/platypush/events/distance.rst b/docs/source/platypush/events/distance.rst new file mode 100644 index 00000000..3292bcb3 --- /dev/null +++ b/docs/source/platypush/events/distance.rst @@ -0,0 +1,5 @@ +``platypush.message.event.distance`` +==================================== + +.. automodule:: platypush.message.event.distance + :members: diff --git a/docs/source/platypush/events/google.pubsub.rst b/docs/source/platypush/events/google.pubsub.rst new file mode 100644 index 00000000..f755f1c1 --- /dev/null +++ b/docs/source/platypush/events/google.pubsub.rst @@ -0,0 +1,5 @@ +``platypush.message.event.google.pubsub`` +========================================= + +.. automodule:: platypush.message.event.google.pubsub + :members: diff --git a/docs/source/platypush/events/google.rst b/docs/source/platypush/events/google.rst new file mode 100644 index 00000000..08cf4a95 --- /dev/null +++ b/docs/source/platypush/events/google.rst @@ -0,0 +1,5 @@ +``platypush.message.event.google`` +================================== + +.. automodule:: platypush.message.event.google + :members: diff --git a/docs/source/platypush/events/gps.rst b/docs/source/platypush/events/gps.rst new file mode 100644 index 00000000..0a7d519e --- /dev/null +++ b/docs/source/platypush/events/gps.rst @@ -0,0 +1,5 @@ +``platypush.message.event.gps`` +=============================== + +.. automodule:: platypush.message.event.gps + :members: diff --git a/docs/source/platypush/events/http.ota.booking.rst b/docs/source/platypush/events/http.ota.booking.rst new file mode 100644 index 00000000..41441113 --- /dev/null +++ b/docs/source/platypush/events/http.ota.booking.rst @@ -0,0 +1,5 @@ +``platypush.message.event.http.ota.booking`` +============================================ + +.. automodule:: platypush.message.event.http.ota.booking + :members: diff --git a/docs/source/platypush/events/mqtt.rst b/docs/source/platypush/events/mqtt.rst new file mode 100644 index 00000000..7ade91ed --- /dev/null +++ b/docs/source/platypush/events/mqtt.rst @@ -0,0 +1,5 @@ +``platypush.message.event.mqtt`` +================================ + +.. automodule:: platypush.message.event.mqtt + :members: diff --git a/docs/source/platypush/events/todoist.rst b/docs/source/platypush/events/todoist.rst new file mode 100644 index 00000000..c97d484b --- /dev/null +++ b/docs/source/platypush/events/todoist.rst @@ -0,0 +1,5 @@ +``platypush.message.event.todoist`` +=================================== + +.. automodule:: platypush.message.event.todoist + :members: diff --git a/docs/source/platypush/events/zeroborg.rst b/docs/source/platypush/events/zeroborg.rst new file mode 100644 index 00000000..31b54873 --- /dev/null +++ b/docs/source/platypush/events/zeroborg.rst @@ -0,0 +1,5 @@ +``platypush.message.event.zeroborg`` +==================================== + +.. automodule:: platypush.message.event.zeroborg + :members: diff --git a/generate_missing_docs.py b/generate_missing_docs.py index 932c34c6..0cc801ab 100644 --- a/generate_missing_docs.py +++ b/generate_missing_docs.py @@ -11,6 +11,10 @@ def get_all_backends(): return get_plugin('inspect').get_all_backends().output +def get_all_events(): + return get_plugin('inspect').get_all_events().output + + # noinspection DuplicatedCode def generate_plugins_doc(): plugins_index = os.path.join(os.path.dirname(os.path.abspath(__file__)), 'docs', 'source', 'plugins.rst') @@ -77,8 +81,41 @@ Backends f.write(' platypush/backend/' + backend + '.rst\n') +# noinspection DuplicatedCode +def generate_events_doc(): + events_index = os.path.join(os.path.dirname(os.path.abspath(__file__)), 'docs', 'source', 'events.rst') + events_dir = os.path.join(os.path.dirname(os.path.abspath(__file__)), 'docs', 'source', 'platypush', 'events') + all_events = sorted(event for event in get_all_events().keys()) + + for event in all_events: + event_file = os.path.join(events_dir, event[len('platypush.message.event.'):] + '.rst') + if not os.path.exists(event_file): + header = '``{}``'.format(event) + divider = '=' * len(header) + body = '\n.. automodule:: {}\n :members:\n'.format(event) + out = '\n'.join([header, divider, body]) + + with open(event_file, 'w') as f: + f.write(out) + + with open(events_index, 'w') as f: + f.write(''' +Events +====== + +.. toctree:: + :maxdepth: 2 + :caption: Events: + +''') + + for event in all_events: + f.write(' platypush/events/' + event[len('platypush.message.event.'):] + '.rst\n') + + generate_plugins_doc() generate_backends_doc() +generate_events_doc() # vim:sw=4:ts=4:et: diff --git a/platypush/plugins/inspect.py b/platypush/plugins/inspect.py index ccf4d03d..82b65854 100644 --- a/platypush/plugins/inspect.py +++ b/platypush/plugins/inspect.py @@ -7,9 +7,11 @@ import threading import platypush.backend import platypush.plugins +import platypush.message.event from platypush.backend import Backend from platypush.plugins import Plugin, action +from platypush.message.event import Event from platypush.utils import get_decorators @@ -60,6 +62,18 @@ class PluginModel(Model): yield attr, getattr(self, attr) +class EventModel(Model): + def __init__(self, event, html_doc: bool = False): + self.package = event.__module__ + self.name = event.__name__ + self.html_doc = html_doc + self.doc = self.to_html(event.__doc__) if html_doc and event.__doc__ else event.__doc__ + + def __iter__(self): + for attr in ['name', 'doc', 'html_doc']: + yield attr, getattr(self, attr) + + class ActionModel(Model): # noinspection PyShadowingNames def __init__(self, action, html_doc: bool = False): @@ -133,8 +147,10 @@ class InspectPlugin(Plugin): super().__init__(**kwargs) self._plugins = {} self._backends = {} + self._events = {} self._plugins_lock = threading.RLock() self._backends_lock = threading.RLock() + self._events_lock = threading.RLock() self._html_doc = False def _init_plugins(self): @@ -175,6 +191,30 @@ class InspectPlugin(Plugin): if model.name: self._backends[model.name] = model + def _init_events(self): + package = platypush.message.event + prefix = package.__name__ + '.' + + for _, modname, _ in pkgutil.walk_packages(path=package.__path__, + prefix=prefix, + onerror=lambda x: None): + # noinspection PyBroadException + try: + module = importlib.import_module(modname) + except: + continue + + for _, obj in inspect.getmembers(module): + if type(obj) == Event: + continue + + if inspect.isclass(obj) and issubclass(obj, Event): + event = EventModel(event=obj, html_doc=self._html_doc) + if event.package not in self._events: + self._events[event.package] = {event.name: event} + else: + self._events[event.package][event.name] = event + @action def get_all_plugins(self, html_doc: bool = None): """ @@ -205,5 +245,23 @@ class InspectPlugin(Plugin): for name, backend in self._backends.items() }) + @action + def get_all_events(self, html_doc: bool = None): + """ + :param html_doc: If True then the docstring will be parsed into HTML (default: False) + """ + with self._events_lock: + if not self._events or (html_doc is not None and html_doc != self._html_doc): + self._html_doc = html_doc + self._init_events() + + return json.dumps({ + package: { + name: dict(event) + for name, event in self._events[package].items() + } + for package, events in self._events.items() + }) + # vim:sw=4:ts=4:et: