From 952a2a937998c564319d4271d6aecf1e6a17ce57 Mon Sep 17 00:00:00 2001
From: Fabio Manganiello <info@fabiomanganiello.com>
Date: Sun, 24 Oct 2021 11:52:08 +0200
Subject: [PATCH] - Render nested attributes in schemas

- Provide relevant examples for schema fields with no description/examples based on the field type

- Fixed RST warnings in Slack plugin

- Fixed list of events in ngrok plugin
---
 docs/source/_ext/sphinx_marshmallow.py | 27 +++++++++++++++++++++++---
 platypush/plugins/ngrok/manifest.yaml  |  6 +++++-
 platypush/plugins/slack/__init__.py    |  4 ++--
 3 files changed, 31 insertions(+), 6 deletions(-)

diff --git a/docs/source/_ext/sphinx_marshmallow.py b/docs/source/_ext/sphinx_marshmallow.py
index 0794f8af55..b08e5c549b 100644
--- a/docs/source/_ext/sphinx_marshmallow.py
+++ b/docs/source/_ext/sphinx_marshmallow.py
@@ -3,10 +3,12 @@ import json
 import os
 import re
 import sys
+from random import randint
 from typing import Union, List
 
 from docutils import nodes
 from docutils.parsers.rst import Directive
+from marshmallow import fields
 
 
 class SchemaDirective(Directive):
@@ -22,10 +24,29 @@ class SchemaDirective(Directive):
 
     sys.path.insert(0, _schemas_path)
 
-    @staticmethod
-    def _get_field_value(field) -> str:
+    @classmethod
+    def _get_field_value(cls, field):
         metadata = getattr(field, 'metadata', {})
-        return metadata.get('example', metadata.get('description', str(field.__class__.__name__).lower()))
+        if metadata.get('example'):
+            return metadata['example']
+        if metadata.get('description'):
+            return metadata['description']
+
+        if isinstance(field, fields.Number):
+            return randint(1, 99)
+        if isinstance(field, fields.Boolean):
+            return bool(randint(0, 1))
+        if isinstance(field, fields.URL):
+            return 'https://example.org'
+        if isinstance(field, fields.Nested):
+            ret = {
+                name: cls._get_field_value(f)
+                for name, f in field.nested().fields.items()
+            }
+
+            return [ret] if field.many else ret
+
+        return str(field.__class__.__name__).lower()
 
     def _parse_schema(self) -> Union[dict, List[dict]]:
         m = self._schema_regex.match('\n'.join(self.content))
diff --git a/platypush/plugins/ngrok/manifest.yaml b/platypush/plugins/ngrok/manifest.yaml
index e8dea9bcef..7df945e523 100644
--- a/platypush/plugins/ngrok/manifest.yaml
+++ b/platypush/plugins/ngrok/manifest.yaml
@@ -1,5 +1,9 @@
 manifest:
-  events: {}
+  events:
+    platypush.message.event.ngrok.NgrokProcessStartedEvent: when the ``ngrok`` process is started.
+    platypush.message.event.ngrok.NgrokProcessStoppedEvent: when the ``ngrok`` process is stopped.
+    platypush.message.event.ngrok.NgrokTunnelStartedEvent: when a tunnel is started.
+    platypush.message.event.ngrok.NgrokTunnelStoppedEvent: when a tunnel is stopped.
   install:
     pip:
     - pyngrok
diff --git a/platypush/plugins/slack/__init__.py b/platypush/plugins/slack/__init__.py
index bbf464fb9d..69a97a5555 100644
--- a/platypush/plugins/slack/__init__.py
+++ b/platypush/plugins/slack/__init__.py
@@ -53,8 +53,8 @@ class SlackPlugin(ChatPlugin, RunnablePlugin):
     def __init__(self, app_token: str, bot_token: str, user_token: Optional[str] = None, **kwargs):
         """
         :param app_token: Your Slack app token.
-        :param bot_token: Bot OAuth token reported on the _Install App_ menu.
-        :param user_token: User OAuth token reported on the _Install App_ menu.
+        :param bot_token: Bot OAuth token reported on the *Install App* menu.
+        :param user_token: User OAuth token reported on the *Install App* menu.
         """
         super().__init__(**kwargs)
         self._app_token = app_token