From e66c02f3de63b962d5078041b0ccf1c02a140a6d Mon Sep 17 00:00:00 2001 From: Fabio Manganiello Date: Thu, 5 Mar 2020 17:39:50 +0100 Subject: [PATCH] Added documentation for response objects as well --- docs/source/index.rst | 3 + docs/source/platypush/responses/bluetooth.rst | 5 ++ .../platypush/responses/camera.android.rst | 5 ++ docs/source/platypush/responses/camera.rst | 5 ++ .../platypush/responses/chat.telegram.rst | 5 ++ .../source/platypush/responses/deepspeech.rst | 5 ++ .../platypush/responses/google.drive.rst | 5 ++ docs/source/platypush/responses/pihole.rst | 5 ++ docs/source/platypush/responses/ping.rst | 5 ++ .../platypush/responses/printer.cups.rst | 5 ++ docs/source/platypush/responses/system.rst | 5 ++ docs/source/platypush/responses/todoist.rst | 5 ++ docs/source/platypush/responses/trello.rst | 5 ++ .../responses/weather.buienradar.rst | 5 ++ docs/source/responses.rst | 21 +++++++ generate_missing_docs.py | 37 +++++++++++++ platypush/plugins/inspect.py | 55 +++++++++++++++++++ 17 files changed, 181 insertions(+) create mode 100644 docs/source/platypush/responses/bluetooth.rst create mode 100644 docs/source/platypush/responses/camera.android.rst create mode 100644 docs/source/platypush/responses/camera.rst create mode 100644 docs/source/platypush/responses/chat.telegram.rst create mode 100644 docs/source/platypush/responses/deepspeech.rst create mode 100644 docs/source/platypush/responses/google.drive.rst create mode 100644 docs/source/platypush/responses/pihole.rst create mode 100644 docs/source/platypush/responses/ping.rst create mode 100644 docs/source/platypush/responses/printer.cups.rst create mode 100644 docs/source/platypush/responses/system.rst create mode 100644 docs/source/platypush/responses/todoist.rst create mode 100644 docs/source/platypush/responses/trello.rst create mode 100644 docs/source/platypush/responses/weather.buienradar.rst create mode 100644 docs/source/responses.rst diff --git a/docs/source/index.rst b/docs/source/index.rst index 39dbb84588..c41c540b65 100644 --- a/docs/source/index.rst +++ b/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 ================== diff --git a/docs/source/platypush/responses/bluetooth.rst b/docs/source/platypush/responses/bluetooth.rst new file mode 100644 index 0000000000..efffa3e1d0 --- /dev/null +++ b/docs/source/platypush/responses/bluetooth.rst @@ -0,0 +1,5 @@ +``platypush.message.response.bluetooth`` +======================================== + +.. automodule:: platypush.message.response.bluetooth + :members: diff --git a/docs/source/platypush/responses/camera.android.rst b/docs/source/platypush/responses/camera.android.rst new file mode 100644 index 0000000000..5ac6225409 --- /dev/null +++ b/docs/source/platypush/responses/camera.android.rst @@ -0,0 +1,5 @@ +``platypush.message.response.camera.android`` +============================================= + +.. automodule:: platypush.message.response.camera.android + :members: diff --git a/docs/source/platypush/responses/camera.rst b/docs/source/platypush/responses/camera.rst new file mode 100644 index 0000000000..80725a55a1 --- /dev/null +++ b/docs/source/platypush/responses/camera.rst @@ -0,0 +1,5 @@ +``platypush.message.response.camera`` +===================================== + +.. automodule:: platypush.message.response.camera + :members: diff --git a/docs/source/platypush/responses/chat.telegram.rst b/docs/source/platypush/responses/chat.telegram.rst new file mode 100644 index 0000000000..8004e322ea --- /dev/null +++ b/docs/source/platypush/responses/chat.telegram.rst @@ -0,0 +1,5 @@ +``platypush.message.response.chat.telegram`` +============================================ + +.. automodule:: platypush.message.response.chat.telegram + :members: diff --git a/docs/source/platypush/responses/deepspeech.rst b/docs/source/platypush/responses/deepspeech.rst new file mode 100644 index 0000000000..bf01d32654 --- /dev/null +++ b/docs/source/platypush/responses/deepspeech.rst @@ -0,0 +1,5 @@ +``platypush.message.response.deepspeech`` +========================================= + +.. automodule:: platypush.message.response.deepspeech + :members: diff --git a/docs/source/platypush/responses/google.drive.rst b/docs/source/platypush/responses/google.drive.rst new file mode 100644 index 0000000000..33bb1b973a --- /dev/null +++ b/docs/source/platypush/responses/google.drive.rst @@ -0,0 +1,5 @@ +``platypush.message.response.google.drive`` +=========================================== + +.. automodule:: platypush.message.response.google.drive + :members: diff --git a/docs/source/platypush/responses/pihole.rst b/docs/source/platypush/responses/pihole.rst new file mode 100644 index 0000000000..932af221e1 --- /dev/null +++ b/docs/source/platypush/responses/pihole.rst @@ -0,0 +1,5 @@ +``platypush.message.response.pihole`` +===================================== + +.. automodule:: platypush.message.response.pihole + :members: diff --git a/docs/source/platypush/responses/ping.rst b/docs/source/platypush/responses/ping.rst new file mode 100644 index 0000000000..e3c3fa0b9a --- /dev/null +++ b/docs/source/platypush/responses/ping.rst @@ -0,0 +1,5 @@ +``platypush.message.response.ping`` +=================================== + +.. automodule:: platypush.message.response.ping + :members: diff --git a/docs/source/platypush/responses/printer.cups.rst b/docs/source/platypush/responses/printer.cups.rst new file mode 100644 index 0000000000..bca7f0e5c4 --- /dev/null +++ b/docs/source/platypush/responses/printer.cups.rst @@ -0,0 +1,5 @@ +``platypush.message.response.printer.cups`` +=========================================== + +.. automodule:: platypush.message.response.printer.cups + :members: diff --git a/docs/source/platypush/responses/system.rst b/docs/source/platypush/responses/system.rst new file mode 100644 index 0000000000..41f4dd3d4f --- /dev/null +++ b/docs/source/platypush/responses/system.rst @@ -0,0 +1,5 @@ +``platypush.message.response.system`` +===================================== + +.. automodule:: platypush.message.response.system + :members: diff --git a/docs/source/platypush/responses/todoist.rst b/docs/source/platypush/responses/todoist.rst new file mode 100644 index 0000000000..c65242a1e9 --- /dev/null +++ b/docs/source/platypush/responses/todoist.rst @@ -0,0 +1,5 @@ +``platypush.message.response.todoist`` +====================================== + +.. automodule:: platypush.message.response.todoist + :members: diff --git a/docs/source/platypush/responses/trello.rst b/docs/source/platypush/responses/trello.rst new file mode 100644 index 0000000000..ce376a3e4d --- /dev/null +++ b/docs/source/platypush/responses/trello.rst @@ -0,0 +1,5 @@ +``platypush.message.response.trello`` +===================================== + +.. automodule:: platypush.message.response.trello + :members: diff --git a/docs/source/platypush/responses/weather.buienradar.rst b/docs/source/platypush/responses/weather.buienradar.rst new file mode 100644 index 0000000000..d48c8fd9eb --- /dev/null +++ b/docs/source/platypush/responses/weather.buienradar.rst @@ -0,0 +1,5 @@ +``platypush.message.response.weather.buienradar`` +================================================= + +.. automodule:: platypush.message.response.weather.buienradar + :members: diff --git a/docs/source/responses.rst b/docs/source/responses.rst new file mode 100644 index 0000000000..38556fd20b --- /dev/null +++ b/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 diff --git a/generate_missing_docs.py b/generate_missing_docs.py index 0cc801abcc..37a425ed23 100644 --- a/generate_missing_docs.py +++ b/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: diff --git a/platypush/plugins/inspect.py b/platypush/plugins/inspect.py index 82b6585493..2cf424ccba 100644 --- a/platypush/plugins/inspect.py +++ b/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: