Added documentation for response objects as well

This commit is contained in:
Fabio Manganiello 2020-03-05 17:39:50 +01:00
parent 5504048c22
commit e66c02f3de
17 changed files with 181 additions and 0 deletions

View file

@ -7,9 +7,11 @@ For more information on Platypush please check out:
* The `GitHub page`_ of the project * The `GitHub page`_ of the project
* The `online wiki`_ for quickstart and examples * The `online wiki`_ for quickstart and examples
* The `Medium stories`_ for inspiration about possible projects
.. _GitHub page: https://github.com/BlackLight/platypush .. _GitHub page: https://github.com/BlackLight/platypush
.. _online wiki: https://github.com/BlackLight/platypush/wiki .. _online wiki: https://github.com/BlackLight/platypush/wiki
.. _Medium stories: https://medium.com/tag/platypush/archive
.. toctree:: .. toctree::
:maxdepth: 3 :maxdepth: 3
@ -18,6 +20,7 @@ For more information on Platypush please check out:
backends backends
plugins plugins
events events
responses
Indices and tables Indices and tables
================== ==================

View file

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

View file

@ -0,0 +1,5 @@
``platypush.message.response.camera.android``
=============================================
.. automodule:: platypush.message.response.camera.android
:members:

View file

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

View file

@ -0,0 +1,5 @@
``platypush.message.response.chat.telegram``
============================================
.. automodule:: platypush.message.response.chat.telegram
:members:

View file

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

View file

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

View file

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

View file

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

View file

@ -0,0 +1,5 @@
``platypush.message.response.printer.cups``
===========================================
.. automodule:: platypush.message.response.printer.cups
:members:

View file

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

View file

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

View file

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

View file

@ -0,0 +1,5 @@
``platypush.message.response.weather.buienradar``
=================================================
.. automodule:: platypush.message.response.weather.buienradar
:members:

21
docs/source/responses.rst Normal file
View file

@ -0,0 +1,21 @@
Responses
=========
.. toctree::
:maxdepth: 2
:caption: Responses:
platypush/responses/bluetooth.rst
platypush/responses/camera.rst
platypush/responses/camera.android.rst
platypush/responses/chat.telegram.rst
platypush/responses/deepspeech.rst
platypush/responses/google.drive.rst
platypush/responses/pihole.rst
platypush/responses/ping.rst
platypush/responses/printer.cups.rst
platypush/responses/system.rst
platypush/responses/todoist.rst
platypush/responses/trello.rst
platypush/responses/weather.buienradar.rst

View file

@ -15,6 +15,10 @@ def get_all_events():
return get_plugin('inspect').get_all_events().output return get_plugin('inspect').get_all_events().output
def get_all_responses():
return get_plugin('inspect').get_all_responses().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')
@ -113,9 +117,42 @@ Events
f.write(' platypush/events/' + event[len('platypush.message.event.'):] + '.rst\n') f.write(' platypush/events/' + event[len('platypush.message.event.'):] + '.rst\n')
# noinspection DuplicatedCode
def generate_responses_doc():
responses_index = os.path.join(os.path.dirname(os.path.abspath(__file__)), 'docs', 'source', 'responses.rst')
responses_dir = os.path.join(os.path.dirname(os.path.abspath(__file__)), 'docs', 'source', 'platypush', 'responses')
all_responses = sorted(response for response in get_all_responses().keys())
for response in all_responses:
response_file = os.path.join(responses_dir, response[len('platypush.message.response.'):] + '.rst')
if not os.path.exists(response_file):
header = '``{}``'.format(response)
divider = '=' * len(header)
body = '\n.. automodule:: {}\n :members:\n'.format(response)
out = '\n'.join([header, divider, body])
with open(response_file, 'w') as f:
f.write(out)
with open(responses_index, 'w') as f:
f.write('''
Responses
=========
.. toctree::
:maxdepth: 2
:caption: Responses:
''')
for response in all_responses:
f.write(' platypush/responses/' + response[len('platypush.message.response.'):] + '.rst\n')
generate_plugins_doc() generate_plugins_doc()
generate_backends_doc() generate_backends_doc()
generate_events_doc() generate_events_doc()
generate_responses_doc()
# vim:sw=4:ts=4:et: # vim:sw=4:ts=4:et:

View file

@ -8,10 +8,12 @@ import threading
import platypush.backend import platypush.backend
import platypush.plugins import platypush.plugins
import platypush.message.event import platypush.message.event
import platypush.message.response
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.message.event import Event
from platypush.message.response import Response
from platypush.utils import get_decorators from platypush.utils import get_decorators
@ -74,6 +76,18 @@ class EventModel(Model):
yield attr, getattr(self, attr) yield attr, getattr(self, attr)
class ResponseModel(Model):
def __init__(self, response, html_doc: bool = False):
self.package = response.__module__
self.name = response.__name__
self.html_doc = html_doc
self.doc = self.to_html(response.__doc__) if html_doc and response.__doc__ else response.__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):
@ -148,9 +162,11 @@ class InspectPlugin(Plugin):
self._plugins = {} self._plugins = {}
self._backends = {} self._backends = {}
self._events = {} self._events = {}
self._responses = {}
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._events_lock = threading.RLock()
self._responses_lock = threading.RLock()
self._html_doc = False self._html_doc = False
def _init_plugins(self): def _init_plugins(self):
@ -215,6 +231,27 @@ class InspectPlugin(Plugin):
else: else:
self._events[event.package][event.name] = event self._events[event.package][event.name] = event
def _init_responses(self):
package = platypush.message.response
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 inspect.isclass(obj) and issubclass(obj, Response):
response = ResponseModel(response=obj, html_doc=self._html_doc)
if response.package not in self._responses:
self._responses[response.package] = {response.name: response}
else:
self._responses[response.package][response.name] = response
@action @action
def get_all_plugins(self, html_doc: bool = None): def get_all_plugins(self, html_doc: bool = None):
""" """
@ -263,5 +300,23 @@ class InspectPlugin(Plugin):
for package, events in self._events.items() for package, events in self._events.items()
}) })
@action
def get_all_responses(self, html_doc: bool = None):
"""
:param html_doc: If True then the docstring will be parsed into HTML (default: False)
"""
with self._responses_lock:
if not self._responses or (html_doc is not None and html_doc != self._html_doc):
self._html_doc = html_doc
self._init_responses()
return json.dumps({
package: {
name: dict(event)
for name, event in self._responses[package].items()
}
for package, events in self._responses.items()
})
# vim:sw=4:ts=4:et: # vim:sw=4:ts=4:et: