Added documentation for response objects as well

docs/source/index.rst

@@ -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
 ==================

docs/source/platypush/responses/bluetooth.rst

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

docs/source/platypush/responses/camera.android.rst

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

docs/source/platypush/responses/camera.rst

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

docs/source/platypush/responses/chat.telegram.rst

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

docs/source/platypush/responses/deepspeech.rst

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

docs/source/platypush/responses/google.drive.rst

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

docs/source/platypush/responses/pihole.rst

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

docs/source/platypush/responses/ping.rst

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

docs/source/platypush/responses/printer.cups.rst

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

docs/source/platypush/responses/system.rst

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

docs/source/platypush/responses/todoist.rst

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

docs/source/platypush/responses/trello.rst

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

docs/source/platypush/responses/weather.buienradar.rst

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

docs/source/responses.rst

@@ -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

generate_missing_docs.py

@@ -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:

platypush/plugins/inspect.py

@@ -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: