Added generation for events docs

This commit is contained in:
Fabio Manganiello 2019-12-30 18:50:01 +01:00
parent cfbf05be24
commit 952a8f2faf
13 changed files with 156 additions and 1 deletions

View file

@ -1,3 +1,4 @@
Events Events
====== ======
@ -5,21 +6,29 @@ Events
:maxdepth: 2 :maxdepth: 2
:caption: Events: :caption: Events:
platypush/events/.rst
platypush/events/adafruit.rst platypush/events/adafruit.rst
platypush/events/application.rst platypush/events/application.rst
platypush/events/assistant.rst platypush/events/assistant.rst
platypush/events/bluetooth.rst
platypush/events/button.flic.rst platypush/events/button.flic.rst
platypush/events/camera.rst platypush/events/camera.rst
platypush/events/distance.rst
platypush/events/geo.rst platypush/events/geo.rst
platypush/events/google.rst
platypush/events/google.fit.rst platypush/events/google.fit.rst
platypush/events/google.pubsub.rst
platypush/events/gps.rst
platypush/events/http.rst platypush/events/http.rst
platypush/events/http.hook.rst platypush/events/http.hook.rst
platypush/events/http.ota.booking.rst
platypush/events/http.rss.rst platypush/events/http.rss.rst
platypush/events/joystick.rst platypush/events/joystick.rst
platypush/events/kafka.rst platypush/events/kafka.rst
platypush/events/light.rst platypush/events/light.rst
platypush/events/media.rst platypush/events/media.rst
platypush/events/midi.rst platypush/events/midi.rst
platypush/events/mqtt.rst
platypush/events/music.rst platypush/events/music.rst
platypush/events/music.snapcast.rst platypush/events/music.snapcast.rst
platypush/events/nfc.rst platypush/events/nfc.rst
@ -33,10 +42,11 @@ Events
platypush/events/sensor.light.rst platypush/events/sensor.light.rst
platypush/events/serial.rst platypush/events/serial.rst
platypush/events/sound.rst platypush/events/sound.rst
platypush/events/todoist.rst
platypush/events/torrent.rst platypush/events/torrent.rst
platypush/events/video.rst platypush/events/video.rst
platypush/events/weather.rst platypush/events/weather.rst
platypush/events/web.rst platypush/events/web.rst
platypush/events/web.widget.rst platypush/events/web.widget.rst
platypush/events/wiimote.rst platypush/events/wiimote.rst
platypush/events/zeroborg.rst

View file

@ -0,0 +1,5 @@
``platypush.message.event``
===========================
.. automodule:: platypush.message.event
:members:

View file

@ -0,0 +1,5 @@
``platypush.message.event.bluetooth``
=====================================
.. automodule:: platypush.message.event.bluetooth
:members:

View file

@ -0,0 +1,5 @@
``platypush.message.event.distance``
====================================
.. automodule:: platypush.message.event.distance
:members:

View file

@ -0,0 +1,5 @@
``platypush.message.event.google.pubsub``
=========================================
.. automodule:: platypush.message.event.google.pubsub
:members:

View file

@ -0,0 +1,5 @@
``platypush.message.event.google``
==================================
.. automodule:: platypush.message.event.google
:members:

View file

@ -0,0 +1,5 @@
``platypush.message.event.gps``
===============================
.. automodule:: platypush.message.event.gps
:members:

View file

@ -0,0 +1,5 @@
``platypush.message.event.http.ota.booking``
============================================
.. automodule:: platypush.message.event.http.ota.booking
:members:

View file

@ -0,0 +1,5 @@
``platypush.message.event.mqtt``
================================
.. automodule:: platypush.message.event.mqtt
:members:

View file

@ -0,0 +1,5 @@
``platypush.message.event.todoist``
===================================
.. automodule:: platypush.message.event.todoist
:members:

View file

@ -0,0 +1,5 @@
``platypush.message.event.zeroborg``
====================================
.. automodule:: platypush.message.event.zeroborg
:members:

View file

@ -11,6 +11,10 @@ def get_all_backends():
return get_plugin('inspect').get_all_backends().output return get_plugin('inspect').get_all_backends().output
def get_all_events():
return get_plugin('inspect').get_all_events().output
# noinspection DuplicatedCode # noinspection DuplicatedCode
def generate_plugins_doc(): def generate_plugins_doc():
plugins_index = os.path.join(os.path.dirname(os.path.abspath(__file__)), 'docs', 'source', 'plugins.rst') 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') 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_plugins_doc()
generate_backends_doc() generate_backends_doc()
generate_events_doc()
# vim:sw=4:ts=4:et: # vim:sw=4:ts=4:et:

View file

@ -7,9 +7,11 @@ import threading
import platypush.backend import platypush.backend
import platypush.plugins import platypush.plugins
import platypush.message.event
from platypush.backend import Backend from platypush.backend import Backend
from platypush.plugins import Plugin, action from platypush.plugins import Plugin, action
from platypush.message.event import Event
from platypush.utils import get_decorators from platypush.utils import get_decorators
@ -60,6 +62,18 @@ class PluginModel(Model):
yield attr, getattr(self, attr) 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): class ActionModel(Model):
# noinspection PyShadowingNames # noinspection PyShadowingNames
def __init__(self, action, html_doc: bool = False): def __init__(self, action, html_doc: bool = False):
@ -133,8 +147,10 @@ class InspectPlugin(Plugin):
super().__init__(**kwargs) super().__init__(**kwargs)
self._plugins = {} self._plugins = {}
self._backends = {} self._backends = {}
self._events = {}
self._plugins_lock = threading.RLock() self._plugins_lock = threading.RLock()
self._backends_lock = threading.RLock() self._backends_lock = threading.RLock()
self._events_lock = threading.RLock()
self._html_doc = False self._html_doc = False
def _init_plugins(self): def _init_plugins(self):
@ -175,6 +191,30 @@ class InspectPlugin(Plugin):
if model.name: if model.name:
self._backends[model.name] = model 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 @action
def get_all_plugins(self, html_doc: bool = None): def get_all_plugins(self, html_doc: bool = None):
""" """
@ -205,5 +245,23 @@ class InspectPlugin(Plugin):
for name, backend in self._backends.items() 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: # vim:sw=4:ts=4:et: