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 `online wiki`_ for quickstart and examples
* The `Medium stories`_ for inspiration about possible projects
.. _GitHub page: https://github.com/BlackLight/platypush
.. _online wiki: https://github.com/BlackLight/platypush/wiki
.. _Medium stories: https://medium.com/tag/platypush/archive
.. toctree::
:maxdepth: 3
@ -18,6 +20,7 @@ For more information on Platypush please check out:
backends
plugins
events
responses
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
def get_all_responses():
return get_plugin('inspect').get_all_responses().output
# noinspection DuplicatedCode
def generate_plugins_doc():
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')
# 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_backends_doc()
generate_events_doc()
generate_responses_doc()
# vim:sw=4:ts=4:et:

View File

@ -8,10 +8,12 @@ import threading
import platypush.backend
import platypush.plugins
import platypush.message.event
import platypush.message.response
from platypush.backend import Backend
from platypush.plugins import Plugin, action
from platypush.message.event import Event
from platypush.message.response import Response
from platypush.utils import get_decorators
@ -74,6 +76,18 @@ class EventModel(Model):
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):
# noinspection PyShadowingNames
def __init__(self, action, html_doc: bool = False):
@ -148,9 +162,11 @@ class InspectPlugin(Plugin):
self._plugins = {}
self._backends = {}
self._events = {}
self._responses = {}
self._plugins_lock = threading.RLock()
self._backends_lock = threading.RLock()
self._events_lock = threading.RLock()
self._responses_lock = threading.RLock()
self._html_doc = False
def _init_plugins(self):
@ -215,6 +231,27 @@ class InspectPlugin(Plugin):
else:
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
def get_all_plugins(self, html_doc: bool = None):
"""
@ -263,5 +300,23 @@ class InspectPlugin(Plugin):
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: