Updated webapp dist files

Added multiple parsers for the entities referenced in docstrings.
The `inspect` plugin can now detect references to plugins, backends, events, responses and schemas in docstrings and replace them either with links to the documentation or auto-generated examples.
2023-05-22 02:24:24 +02:00 · 2023-05-22 02:20:58 +02:00
101 changed files with 517 additions and 159 deletions
--- a/platypush/backend/http/webapp/dist/index.html
+++ b/platypush/backend/http/webapp/dist/index.html
@ -1 +1 @@
-<!doctype html><html lang="en"><head><meta charset="utf-8"><meta http-equiv="X-UA-Compatible" content="IE=edge"><meta name="viewport" content="width=device-width,initial-scale=1"><!--[if IE]><link rel="icon" href="/favicon.ico"><![endif]--><link rel="stylesheet" href="/fonts/poppins.css"><title>platypush</title><script defer="defer" type="module" src="/static/js/chunk-vendors.0f6060b6.js"></script><script defer="defer" type="module" src="/static/js/app.a6e85f1f.js"></script><link href="/static/css/chunk-vendors.0fcd36f0.css" rel="stylesheet"><link href="/static/css/app.cf51ffe1.css" rel="stylesheet"><link rel="icon" type="image/svg+xml" href="/img/icons/favicon.svg"><link rel="icon" type="image/png" sizes="32x32" href="/img/icons/favicon-32x32.png"><link rel="icon" type="image/png" sizes="16x16" href="/img/icons/favicon-16x16.png"><link rel="manifest" href="/manifest.json"><meta name="theme-color" content="#ffffff"><meta name="apple-mobile-web-app-capable" content="no"><meta name="apple-mobile-web-app-status-bar-style" content="default"><meta name="apple-mobile-web-app-title" content="Platypush"><link rel="apple-touch-icon" href="/img/icons/apple-touch-icon-152x152.png"><link rel="mask-icon" href="/img/icons/safari-pinned-tab.svg" color="#ffffff"><meta name="msapplication-TileImage" content="/img/icons/msapplication-icon-144x144.png"><meta name="msapplication-TileColor" content="#000000"><script defer="defer" src="/static/js/chunk-vendors-legacy.037e71b7.js" nomodule></script><script defer="defer" src="/static/js/app-legacy.9462d538.js" nomodule></script></head><body><noscript><strong>We're sorry but platypush doesn't work properly without JavaScript enabled. Please enable it to continue.</strong></noscript><div id="app"></div></body></html>
+<!doctype html><html lang="en"><head><meta charset="utf-8"><meta http-equiv="X-UA-Compatible" content="IE=edge"><meta name="viewport" content="width=device-width,initial-scale=1"><!--[if IE]><link rel="icon" href="/favicon.ico"><![endif]--><link rel="stylesheet" href="/fonts/poppins.css"><title>platypush</title><script defer="defer" type="module" src="/static/js/chunk-vendors.0f6060b6.js"></script><script defer="defer" type="module" src="/static/js/app.55199c6f.js"></script><link href="/static/css/chunk-vendors.0fcd36f0.css" rel="stylesheet"><link href="/static/css/app.72325ef5.css" rel="stylesheet"><link rel="icon" type="image/svg+xml" href="/img/icons/favicon.svg"><link rel="icon" type="image/png" sizes="32x32" href="/img/icons/favicon-32x32.png"><link rel="icon" type="image/png" sizes="16x16" href="/img/icons/favicon-16x16.png"><link rel="manifest" href="/manifest.json"><meta name="theme-color" content="#ffffff"><meta name="apple-mobile-web-app-capable" content="no"><meta name="apple-mobile-web-app-status-bar-style" content="default"><meta name="apple-mobile-web-app-title" content="Platypush"><link rel="apple-touch-icon" href="/img/icons/apple-touch-icon-152x152.png"><link rel="mask-icon" href="/img/icons/safari-pinned-tab.svg" color="#ffffff"><meta name="msapplication-TileImage" content="/img/icons/msapplication-icon-144x144.png"><meta name="msapplication-TileColor" content="#000000"><script defer="defer" src="/static/js/chunk-vendors-legacy.037e71b7.js" nomodule></script><script defer="defer" src="/static/js/app-legacy.08491679.js" nomodule></script></head><body><noscript><strong>We're sorry but platypush doesn't work properly without JavaScript enabled. Please enable it to continue.</strong></noscript><div id="app"></div></body></html>
--- a/platypush/backend/http/webapp/dist/service-worker.js
+++ b/platypush/backend/http/webapp/dist/service-worker.js
--- a/platypush/backend/http/webapp/dist/service-worker.js.map
+++ b/platypush/backend/http/webapp/dist/service-worker.js.map
--- a/platypush/backend/http/webapp/dist/static/css/1196.78925ff5.css
+++ b/platypush/backend/http/webapp/dist/static/css/1196.78925ff5.css
--- a/platypush/backend/http/webapp/dist/static/css/1300.180d2070.css
+++ b/platypush/backend/http/webapp/dist/static/css/1300.180d2070.css
--- a/platypush/backend/http/webapp/dist/static/css/1767.f9545a14.css
+++ b/platypush/backend/http/webapp/dist/static/css/1767.f9545a14.css
--- a/platypush/backend/http/webapp/dist/static/css/1798.3a165bb4.css
+++ b/platypush/backend/http/webapp/dist/static/css/1798.3a165bb4.css
--- a/platypush/backend/http/webapp/dist/static/css/1818.8db287b9.css
+++ b/platypush/backend/http/webapp/dist/static/css/1818.8db287b9.css
--- a/platypush/backend/http/webapp/dist/static/css/201.11f5843f.css
+++ b/platypush/backend/http/webapp/dist/static/css/201.11f5843f.css
--- a/platypush/backend/http/webapp/dist/static/css/201.3ba92d09.css
+++ b/platypush/backend/http/webapp/dist/static/css/201.3ba92d09.css
--- a/platypush/backend/http/webapp/dist/static/css/2346.ed463bd2.css
+++ b/platypush/backend/http/webapp/dist/static/css/2346.ed463bd2.css
--- a/platypush/backend/http/webapp/dist/static/css/2790.19201b3b.css
+++ b/platypush/backend/http/webapp/dist/static/css/2790.19201b3b.css
--- a/platypush/backend/http/webapp/dist/static/css/2790.a0725ecc.css
+++ b/platypush/backend/http/webapp/dist/static/css/2790.a0725ecc.css
--- a/platypush/backend/http/webapp/dist/static/css/2806.9c9d5a57.css
+++ b/platypush/backend/http/webapp/dist/static/css/2806.9c9d5a57.css
--- a/platypush/backend/http/webapp/dist/static/css/2989.22b025de.css
+++ b/platypush/backend/http/webapp/dist/static/css/2989.22b025de.css
--- a/platypush/backend/http/webapp/dist/static/css/3194.a07dd4e2.css
+++ b/platypush/backend/http/webapp/dist/static/css/3194.a07dd4e2.css
--- a/platypush/backend/http/webapp/dist/static/css/3303.bfeafcb0.css
+++ b/platypush/backend/http/webapp/dist/static/css/3303.bfeafcb0.css
--- a/platypush/backend/http/webapp/dist/static/css/345.25d1c562.css
+++ b/platypush/backend/http/webapp/dist/static/css/345.25d1c562.css
--- a/platypush/backend/http/webapp/dist/static/css/346.1706fbde.css
+++ b/platypush/backend/http/webapp/dist/static/css/346.1706fbde.css
--- a/platypush/backend/http/webapp/dist/static/css/346.bec1b050.css
+++ b/platypush/backend/http/webapp/dist/static/css/346.bec1b050.css
--- a/platypush/backend/http/webapp/dist/static/css/3490.fcf11255.css
+++ b/platypush/backend/http/webapp/dist/static/css/3490.fcf11255.css
--- a/platypush/backend/http/webapp/dist/static/css/3710.1112d8b7.css
+++ b/platypush/backend/http/webapp/dist/static/css/3710.1112d8b7.css
--- a/platypush/backend/http/webapp/dist/static/css/3724.234438b4.css
+++ b/platypush/backend/http/webapp/dist/static/css/3724.234438b4.css
--- a/platypush/backend/http/webapp/dist/static/css/4021.58663e3e.css
+++ b/platypush/backend/http/webapp/dist/static/css/4021.58663e3e.css
--- a/platypush/backend/http/webapp/dist/static/css/4196.539db457.css
+++ b/platypush/backend/http/webapp/dist/static/css/4196.539db457.css
--- a/platypush/backend/http/webapp/dist/static/css/4196.ea56d2c9.css
+++ b/platypush/backend/http/webapp/dist/static/css/4196.ea56d2c9.css
--- a/platypush/backend/http/webapp/dist/static/css/4848.72a7d113.css
+++ b/platypush/backend/http/webapp/dist/static/css/4848.72a7d113.css
--- a/platypush/backend/http/webapp/dist/static/css/4848.c9eab7f4.css
+++ b/platypush/backend/http/webapp/dist/static/css/4848.c9eab7f4.css
--- a/platypush/backend/http/webapp/dist/static/css/4981.94bc04e2.css
+++ b/platypush/backend/http/webapp/dist/static/css/4981.94bc04e2.css
--- a/platypush/backend/http/webapp/dist/static/css/4981.c5c2f5dd.css
+++ b/platypush/backend/http/webapp/dist/static/css/4981.c5c2f5dd.css
--- a/platypush/backend/http/webapp/dist/static/css/5193.47f020c5.css
+++ b/platypush/backend/http/webapp/dist/static/css/5193.47f020c5.css
--- a/platypush/backend/http/webapp/dist/static/css/5199.6ad0f775.css
+++ b/platypush/backend/http/webapp/dist/static/css/5199.6ad0f775.css
--- a/platypush/backend/http/webapp/dist/static/css/5199.fe9cee1a.css
+++ b/platypush/backend/http/webapp/dist/static/css/5199.fe9cee1a.css
--- a/platypush/backend/http/webapp/dist/static/css/5207.950597e1.css
+++ b/platypush/backend/http/webapp/dist/static/css/5207.950597e1.css
--- a/platypush/backend/http/webapp/dist/static/css/5498.ef565a73.css
+++ b/platypush/backend/http/webapp/dist/static/css/5498.ef565a73.css
--- a/platypush/backend/http/webapp/dist/static/css/5528.22b025de.css
+++ b/platypush/backend/http/webapp/dist/static/css/5528.22b025de.css
--- a/platypush/backend/http/webapp/dist/static/css/5824.8f1b2b15.css
+++ b/platypush/backend/http/webapp/dist/static/css/5824.8f1b2b15.css
--- a/platypush/backend/http/webapp/dist/static/css/5824.c1f06cf8.css
+++ b/platypush/backend/http/webapp/dist/static/css/5824.c1f06cf8.css
--- a/platypush/backend/http/webapp/dist/static/css/5924.f0111959.css
+++ b/platypush/backend/http/webapp/dist/static/css/5924.f0111959.css
--- a/platypush/backend/http/webapp/dist/static/css/6003.fbbaf2b7.css
+++ b/platypush/backend/http/webapp/dist/static/css/6003.fbbaf2b7.css
--- a/platypush/backend/http/webapp/dist/static/css/6013.504d6c0b.css
+++ b/platypush/backend/http/webapp/dist/static/css/6013.504d6c0b.css
--- a/platypush/backend/http/webapp/dist/static/css/615.6d3a8446.css
+++ b/platypush/backend/http/webapp/dist/static/css/615.6d3a8446.css
--- a/platypush/backend/http/webapp/dist/static/css/6162.748a42fd.css
+++ b/platypush/backend/http/webapp/dist/static/css/6162.748a42fd.css
--- a/platypush/backend/http/webapp/dist/static/css/6162.c92d9d38.css
+++ b/platypush/backend/http/webapp/dist/static/css/6162.c92d9d38.css
--- a/platypush/backend/http/webapp/dist/static/css/6164.ea3fa7cb.css
+++ b/platypush/backend/http/webapp/dist/static/css/6164.ea3fa7cb.css
--- a/platypush/backend/http/webapp/dist/static/css/6358.1f06089f.css
+++ b/platypush/backend/http/webapp/dist/static/css/6358.1f06089f.css
--- a/platypush/backend/http/webapp/dist/static/css/65.ae3723d7.css
+++ b/platypush/backend/http/webapp/dist/static/css/65.ae3723d7.css
--- a/platypush/backend/http/webapp/dist/static/css/6739.49b1f262.css
+++ b/platypush/backend/http/webapp/dist/static/css/6739.49b1f262.css
--- a/platypush/backend/http/webapp/dist/static/css/675.10cdb721.css
+++ b/platypush/backend/http/webapp/dist/static/css/675.10cdb721.css
--- a/platypush/backend/http/webapp/dist/static/css/6815.f1dc7909.css
+++ b/platypush/backend/http/webapp/dist/static/css/6815.f1dc7909.css
--- a/platypush/backend/http/webapp/dist/static/css/6833.28cb5e3d.css
+++ b/platypush/backend/http/webapp/dist/static/css/6833.28cb5e3d.css
--- a/platypush/backend/http/webapp/dist/static/css/6833.b5d8115c.css
+++ b/platypush/backend/http/webapp/dist/static/css/6833.b5d8115c.css
--- a/platypush/backend/http/webapp/dist/static/css/6899.748a42fd.css
+++ b/platypush/backend/http/webapp/dist/static/css/6899.748a42fd.css
--- a/platypush/backend/http/webapp/dist/static/css/6899.c92d9d38.css
+++ b/platypush/backend/http/webapp/dist/static/css/6899.c92d9d38.css
--- a/platypush/backend/http/webapp/dist/static/css/7029.b34577f7.css
+++ b/platypush/backend/http/webapp/dist/static/css/7029.b34577f7.css
--- a/platypush/backend/http/webapp/dist/static/css/7029.b6585c35.css
+++ b/platypush/backend/http/webapp/dist/static/css/7029.b6585c35.css
--- a/platypush/backend/http/webapp/dist/static/css/7141.4b3e6b00.css
+++ b/platypush/backend/http/webapp/dist/static/css/7141.4b3e6b00.css
--- a/platypush/backend/http/webapp/dist/static/css/7420.4bf56b11.css
+++ b/platypush/backend/http/webapp/dist/static/css/7420.4bf56b11.css
--- a/platypush/backend/http/webapp/dist/static/css/7503.34698020.css
+++ b/platypush/backend/http/webapp/dist/static/css/7503.34698020.css
--- a/platypush/backend/http/webapp/dist/static/css/7782.a6a32303.css
+++ b/platypush/backend/http/webapp/dist/static/css/7782.a6a32303.css
--- a/platypush/backend/http/webapp/dist/static/css/779.2e68c420.css
+++ b/platypush/backend/http/webapp/dist/static/css/779.2e68c420.css
--- a/platypush/backend/http/webapp/dist/static/css/8135.1460504e.css
+++ b/platypush/backend/http/webapp/dist/static/css/8135.1460504e.css
--- a/platypush/backend/http/webapp/dist/static/css/8444.95911650.css
+++ b/platypush/backend/http/webapp/dist/static/css/8444.95911650.css
--- a/platypush/backend/http/webapp/dist/static/css/8448.6ad0f775.css
+++ b/platypush/backend/http/webapp/dist/static/css/8448.6ad0f775.css
--- a/platypush/backend/http/webapp/dist/static/css/8448.fe9cee1a.css
+++ b/platypush/backend/http/webapp/dist/static/css/8448.fe9cee1a.css
--- a/platypush/backend/http/webapp/dist/static/css/8589.2e68c420.css
+++ b/platypush/backend/http/webapp/dist/static/css/8589.2e68c420.css
--- a/platypush/backend/http/webapp/dist/static/css/906.a114eea0.css
+++ b/platypush/backend/http/webapp/dist/static/css/906.a114eea0.css
--- a/platypush/backend/http/webapp/dist/static/css/906.cb3bce26.css
+++ b/platypush/backend/http/webapp/dist/static/css/906.cb3bce26.css
--- a/platypush/backend/http/webapp/dist/static/css/9276.518b169b.css
+++ b/platypush/backend/http/webapp/dist/static/css/9276.518b169b.css
--- a/platypush/backend/http/webapp/dist/static/css/9387.74d3b3a3.css
+++ b/platypush/backend/http/webapp/dist/static/css/9387.74d3b3a3.css
--- a/platypush/backend/http/webapp/dist/static/css/9418.9f2b9c3a.css
+++ b/platypush/backend/http/webapp/dist/static/css/9418.9f2b9c3a.css
--- a/platypush/backend/http/webapp/dist/static/css/9450.fd9ed6f2.css
+++ b/platypush/backend/http/webapp/dist/static/css/9450.fd9ed6f2.css
--- a/platypush/backend/http/webapp/dist/static/css/9575.1b22f65c.css
+++ b/platypush/backend/http/webapp/dist/static/css/9575.1b22f65c.css
--- a/platypush/backend/http/webapp/dist/static/css/9978.b34577f7.css
+++ b/platypush/backend/http/webapp/dist/static/css/9978.b34577f7.css
--- a/platypush/backend/http/webapp/dist/static/css/9978.b6585c35.css
+++ b/platypush/backend/http/webapp/dist/static/css/9978.b6585c35.css
--- a/platypush/backend/http/webapp/dist/static/css/app.72325ef5.css
+++ b/platypush/backend/http/webapp/dist/static/css/app.72325ef5.css
--- a/platypush/backend/http/webapp/dist/static/css/app.cf51ffe1.css
+++ b/platypush/backend/http/webapp/dist/static/css/app.cf51ffe1.css
--- a/platypush/backend/http/webapp/dist/static/js/3710-legacy.c79204f1.js
+++ b/platypush/backend/http/webapp/dist/static/js/3710-legacy.c79204f1.js
--- a/platypush/backend/http/webapp/dist/static/js/3710-legacy.c79204f1.js.map
+++ b/platypush/backend/http/webapp/dist/static/js/3710-legacy.c79204f1.js.map
--- a/platypush/backend/http/webapp/dist/static/js/3710.05c41d28.js
+++ b/platypush/backend/http/webapp/dist/static/js/3710.05c41d28.js
--- a/platypush/backend/http/webapp/dist/static/js/3710.05c41d28.js.map
+++ b/platypush/backend/http/webapp/dist/static/js/3710.05c41d28.js.map
--- a/platypush/backend/http/webapp/dist/static/js/3956-legacy.489057d5.js
+++ b/platypush/backend/http/webapp/dist/static/js/3956-legacy.489057d5.js
--- a/platypush/backend/http/webapp/dist/static/js/3956-legacy.489057d5.js.map
+++ b/platypush/backend/http/webapp/dist/static/js/3956-legacy.489057d5.js.map
--- a/platypush/backend/http/webapp/dist/static/js/3956.7c792927.js
+++ b/platypush/backend/http/webapp/dist/static/js/3956.7c792927.js
--- a/platypush/backend/http/webapp/dist/static/js/3956.7c792927.js.map
+++ b/platypush/backend/http/webapp/dist/static/js/3956.7c792927.js.map
--- a/platypush/backend/http/webapp/dist/static/js/app-legacy.08491679.js
+++ b/platypush/backend/http/webapp/dist/static/js/app-legacy.08491679.js
--- a/platypush/backend/http/webapp/dist/static/js/app-legacy.08491679.js.map
+++ b/platypush/backend/http/webapp/dist/static/js/app-legacy.08491679.js.map
--- a/platypush/backend/http/webapp/dist/static/js/app.55199c6f.js
+++ b/platypush/backend/http/webapp/dist/static/js/app.55199c6f.js
--- a/platypush/backend/http/webapp/dist/static/js/app.55199c6f.js.map
+++ b/platypush/backend/http/webapp/dist/static/js/app.55199c6f.js.map
--- a/platypush/backend/http/webapp/src/components/Nav.vue
+++ b/platypush/backend/http/webapp/src/components/Nav.vue
@ -156,6 +156,8 @@ nav {
      display: block;
      color: $nav-fg;
      padding: 1em 0.5em;
+      text-decoration: none;
+
      &:hover {
        color: $nav-fg;
      }
--- a/platypush/backend/http/webapp/src/components/panels/Execute/Index.vue
+++ b/platypush/backend/http/webapp/src/components/panels/Execute/Index.vue
@ -1,5 +1,5 @@
 <template>
-  <div class="row plugin execute-container">
+  <div class="row plugin execute-container" @click="onClick">
    <Loading v-if="loading" />
    <div class="section command-container">
      <div class="section-title">Execute Action</div>
@ -32,7 +32,7 @@

          <div class="doc-container" v-if="selectedDoc">
            <div class="title">
-              Action documentation
+              <a :href="currentActionDocURL">Action documentation</a>
            </div>

            <div class="doc html">
@ -217,6 +217,24 @@ export default {
    }
  },

+  computed: {
+    currentActionDocURL() {
+      if (!this.action?.name?.length)
+        return undefined
+
+      const plugin = this.action.name.split('.').slice(0, -1).join('.')
+      const actionName = this.action.name.split('.').slice(-1)
+      const actionClass = this.action.name
+        .split('.')
+        .slice(0, -1)
+        .map((token) => token.slice(0, 1).toUpperCase() + token.slice(1))
+        .join('') + 'Plugin'
+
+      return 'https://docs.platypush.tech/platypush/plugins/' +
+        `${plugin}.html#platypush.plugins.${plugin}.${actionClass}.${actionName}`
+    },
+  },
+
  methods: {
    async refresh() {
      this.loading = true
@ -457,6 +475,15 @@ export default {
      this.request('procedure.' + this.selectedProcedure.name, args)
          .then(this.onResponse).catch(this.onError).finally(this.onDone)
    },
+
+    onClick(event) {
+      // Intercept any clicks from RST rendered links and open them in a new tab
+      if (event.target.tagName.toLowerCase() === 'a') {
+        event.stopPropagation()
+        event.preventDefault()
+        window.open(event.target.getAttribute('href', '_blank'))
+      }
+    },
  },

  mounted() {
@ -857,6 +884,10 @@ $request-headers-btn-width: 7.5em;
        background: $procedure-submit-btn-bg;
      }
    }
+
+    .action-param-value {
+      margin: 0.25em 0;
+    }
  }

  pre {
--- a/platypush/backend/http/webapp/src/style/components.scss
+++ b/platypush/backend/http/webapp/src/style/components.scss
@ -42,8 +42,13 @@ ul {
 }

 a {
+  color: $default-link-fg;
+  text-decoration: underline dotted;
  cursor: pointer;
-  text-decoration: none;
+
+  &:hover {
+    color: $default-hover-fg;
+  }
 }

 ::-webkit-scrollbar {
--- a/platypush/plugins/inspect/_model.py
+++ b/platypush/plugins/inspect/_model.py
@ -1,7 +1,7 @@
 import inspect
 import json
 import re
-from typing import Optional, Type
+from typing import Callable, Optional, Type

 from platypush.backend import Backend
 from platypush.message.event import Event
@ -9,12 +9,30 @@ from platypush.message.response import Response
 from platypush.plugins import Plugin
 from platypush.utils import get_decorators

+from ._parsers import (
+    BackendParser,
+    EventParser,
+    MethodParser,
+    PluginParser,
+    ResponseParser,
+    SchemaParser,
+)
+

 class Model:
    """
    Base class for component models.
    """

+    _parsers = [
+        BackendParser,
+        EventParser,
+        MethodParser,
+        PluginParser,
+        ResponseParser,
+        SchemaParser,
+    ]
+
    def __init__(
        self,
        obj_type: type,
@ -32,8 +50,22 @@ class Model:
        self._obj_type = obj_type
        self.package = obj_type.__module__[len(prefix) :]
        self.name = name or self.package
-        self.doc = doc or obj_type.__doc__
        self.last_modified = last_modified
+        self.doc, argsdoc = self._parse_docstring(doc or obj_type.__doc__ or '')
+        self.args = {}
+        self.has_kwargs = False
+
+        for arg in list(inspect.signature(obj_type).parameters.values())[1:]:
+            if arg.kind == arg.VAR_KEYWORD:
+                self.has_kwargs = True
+                continue
+
+            self.args[arg.name] = {
+                'default': arg.default
+                if not issubclass(arg.default.__class__, type)
+                else None,
+                'doc': argsdoc.get(arg.name),
+            }

    def __str__(self):
        """
@ -51,9 +83,62 @@ class Model:
        """
        Iterator for the model public attributes/values pairs.
        """
-        for attr in ['name', 'doc']:
+        for attr in ['name', 'args', 'doc', 'has_kwargs']:
            yield attr, getattr(self, attr)

+    @classmethod
+    def _parse_docstring(cls, docstring: str):
+        new_docstring = ''
+        params = {}
+        cur_param = None
+        cur_param_docstring = ''
+
+        if not docstring:
+            return None, {}
+
+        for line in docstring.split('\n'):
+            m = re.match(r'^\s*:param ([^:]+):\s*(.*)', line)
+            if m:
+                if cur_param:
+                    params[cur_param] = cur_param_docstring
+
+                cur_param = m.group(1)
+                cur_param_docstring = m.group(2)
+                continue
+
+            m = re.match(r'^\s*:return:\s+(.*)', line)
+            if m:
+                if cur_param:
+                    params[cur_param] = cur_param_docstring
+
+                new_docstring += '\n\n**Returns:**\n\n' + m.group(1).strip() + ' '
+                cur_param = None
+                continue
+
+            if cur_param:
+                if not line.strip():
+                    params[cur_param] = cur_param_docstring
+                    cur_param = None
+                    cur_param_docstring = ''
+                else:
+                    cur_param_docstring += '\n' + line.strip() + ' '
+            else:
+                new_docstring += line + '\n'
+
+        if cur_param:
+            params[cur_param] = cur_param_docstring
+
+        for param, doc in params.items():
+            params[param] = cls._post_process_docstring(doc)
+
+        return cls._post_process_docstring(new_docstring), params
+
+    @classmethod
+    def _post_process_docstring(cls, docstring: str) -> str:
+        for parsers in cls._parsers:
+            docstring = parsers.parse(docstring)
+        return docstring.strip()
+

 # pylint: disable=too-few-public-methods
 class BackendModel(Model):
@ -90,7 +175,7 @@ class PluginModel(Model):
        Overrides the default implementation of ``__iter__`` to also include
        plugin actions.
        """
-        for attr in ['name', 'actions', 'doc']:
+        for attr in ['name', 'args', 'actions', 'doc', 'has_kwargs']:
            if attr == 'actions':
                yield attr, {
                    name: dict(action) for name, action in self.actions.items()
@ -122,66 +207,5 @@ class ActionModel(Model):
    Model for plugin action components.
    """

-    def __init__(self, action, **kwargs):
-        doc, argsdoc = self._parse_docstring(action.__doc__)
-        super().__init__(action, name=action.__name__, doc=doc, **kwargs)
-
-        self.args = {}
-        self.has_kwargs = False
-
-        for arg in list(inspect.signature(action).parameters.values())[1:]:
-            if arg.kind == arg.VAR_KEYWORD:
-                self.has_kwargs = True
-                continue
-
-            self.args[arg.name] = {
-                'default': arg.default
-                if not issubclass(arg.default.__class__, type)
-                else None,
-                'doc': argsdoc.get(arg.name),
-            }
-
-    @classmethod
-    def _parse_docstring(cls, docstring: str):
-        new_docstring = ''
-        params = {}
-        cur_param = None
-        cur_param_docstring = ''
-
-        if not docstring:
-            return None, {}
-
-        for line in docstring.split('\n'):
-            if m := re.match(r'^\s*:param ([^:]+):\s*(.*)', line):
-                if cur_param:
-                    params[cur_param] = cur_param_docstring
-
-                cur_param = m.group(1)
-                cur_param_docstring = m.group(2)
-            elif m := re.match(r'^\s*:return:\s+(.*)', line):
-                if cur_param:
-                    params[cur_param] = cur_param_docstring
-
-                new_docstring += '\n\n**Returns:**\n\n' + m.group(1).strip() + ' '
-                cur_param = None
-            elif re.match(r'^\s*:[^:]+:\s*.*', line):
-                continue
-            else:
-                if cur_param:
-                    if not line.strip():
-                        params[cur_param] = cur_param_docstring
-                        cur_param = None
-                        cur_param_docstring = ''
-                    else:
-                        cur_param_docstring += '\n' + line.strip() + ' '
-                else:
-                    new_docstring += line.strip() + ' '
-
-        if cur_param:
-            params[cur_param] = cur_param_docstring
-
-        return new_docstring.strip(), params
-
-    def __iter__(self):
-        for attr in ['name', 'args', 'doc', 'has_kwargs']:
-            yield attr, getattr(self, attr)
+    def __init__(self, obj_type: Type[Callable], *args, **kwargs):
+        super().__init__(obj_type, name=obj_type.__name__, *args, **kwargs)
--- a/platypush/plugins/inspect/_parsers/init.py
+++ b/platypush/plugins/inspect/_parsers/init.py
@ -0,0 +1,16 @@
+from ._backend import BackendParser
+from ._event import EventParser
+from ._method import MethodParser
+from ._plugin import PluginParser
+from ._response import ResponseParser
+from ._schema import SchemaParser
+
+
+__all__ = [
+    'BackendParser',
+    'EventParser',
+    'MethodParser',
+    'PluginParser',
+    'ResponseParser',
+    'SchemaParser',
+]
--- a/platypush/plugins/inspect/_parsers/_backend.py
+++ b/platypush/plugins/inspect/_parsers/_backend.py
@ -0,0 +1,34 @@
+import re
+from typing_extensions import override
+
+from ._base import Parser
+
+
+class BackendParser(Parser):
+    """
+    Parse backend references in the docstrings with rendered links to their
+    respective documentation.
+    """
+
+    _backend_regex = re.compile(
+        r'(\s*):class:`(platypush\.backend\.(.+?))`', re.MULTILINE
+    )
+
+    @override
+    @classmethod
+    def parse(cls, docstring: str) -> str:
+        while True:
+            m = cls._backend_regex.search(docstring)
+            if not m:
+                break
+
+            class_name = m.group(3).split('.')[-1]
+            package = '.'.join(m.group(3).split('.')[:-1])
+            docstring = cls._backend_regex.sub(
+                f'{m.group(1)}`{class_name} '
+                f'<https://docs.platypush.tech/platypush/backend/{package}.html#{m.group(2)}>`_',
+                docstring,
+                count=1,
+            )
+
+        return docstring
--- a/platypush/plugins/inspect/_parsers/_base.py
+++ b/platypush/plugins/inspect/_parsers/_base.py
@ -0,0 +1,12 @@
+from abc import ABC, abstractmethod
+
+
+class Parser(ABC):
+    """
+    Base class for parsers.
+    """
+
+    @classmethod
+    @abstractmethod
+    def parse(cls, docstring: str) -> str:
+        raise NotImplementedError()
--- a/platypush/plugins/inspect/_parsers/_event.py
+++ b/platypush/plugins/inspect/_parsers/_event.py
@ -0,0 +1,34 @@
+import re
+from typing_extensions import override
+
+from ._base import Parser
+
+
+class EventParser(Parser):
+    """
+    Parse event references in the docstrings with rendered links to their
+    respective documentation.
+    """
+
+    _event_regex = re.compile(
+        r'(\s*):class:`(platypush\.message\.event\.(.+?))`', re.MULTILINE
+    )
+
+    @override
+    @classmethod
+    def parse(cls, docstring: str) -> str:
+        while True:
+            m = cls._event_regex.search(docstring)
+            if not m:
+                break
+
+            class_name = m.group(3).split('.')[-1]
+            package = '.'.join(m.group(3).split('.')[:-1])
+            docstring = cls._event_regex.sub(
+                f'{m.group(1)}`{class_name} '
+                f'<https://docs.platypush.tech/platypush/events/{package}.html#{m.group(2)}>`_',
+                docstring,
+                count=1,
+            )
+
+        return docstring
--- a/platypush/plugins/inspect/_parsers/_method.py
+++ b/platypush/plugins/inspect/_parsers/_method.py
@ -0,0 +1,35 @@
+import re
+from typing_extensions import override
+
+from ._base import Parser
+
+
+class MethodParser(Parser):
+    """
+    Parse method references in the docstrings with rendered links to their
+    respective documentation.
+    """
+
+    _method_regex = re.compile(
+        r'(\s*):meth:`(platypush\.plugins\.(.+?))`', re.MULTILINE
+    )
+
+    @override
+    @classmethod
+    def parse(cls, docstring: str) -> str:
+        while True:
+            m = cls._method_regex.search(docstring)
+            if not m:
+                break
+
+            tokens = m.group(3).split('.')
+            method = tokens[-1]
+            package = '.'.join(tokens[:-2])
+            docstring = cls._method_regex.sub(
+                f'{m.group(1)}`{package}.{method} '
+                f'<https://docs.platypush.tech/platypush/plugins/{package}.html#{m.group(2)}>`_',
+                docstring,
+                count=1,
+            )
+
+        return docstring
--- a/platypush/plugins/inspect/_parsers/_plugin.py
+++ b/platypush/plugins/inspect/_parsers/_plugin.py
@ -0,0 +1,34 @@
+import re
+from typing_extensions import override
+
+from ._base import Parser
+
+
+class PluginParser(Parser):
+    """
+    Parse plugin references in the docstrings with rendered links to their
+    respective documentation.
+    """
+
+    _plugin_regex = re.compile(
+        r'(\s*):class:`(platypush\.plugins\.(.+?))`', re.MULTILINE
+    )
+
+    @override
+    @classmethod
+    def parse(cls, docstring: str) -> str:
+        while True:
+            m = cls._plugin_regex.search(docstring)
+            if not m:
+                break
+
+            class_name = m.group(3).split('.')[-1]
+            package = '.'.join(m.group(3).split('.')[:-1])
+            docstring = cls._plugin_regex.sub(
+                f'{m.group(1)}`{class_name} '
+                f'<https://docs.platypush.tech/platypush/plugins/{package}.html#{m.group(2)}>`_',
+                docstring,
+                count=1,
+            )
+
+        return docstring
--- a/platypush/plugins/inspect/_parsers/_response.py
+++ b/platypush/plugins/inspect/_parsers/_response.py
@ -0,0 +1,34 @@
+import re
+from typing_extensions import override
+
+from ._base import Parser
+
+
+class ResponseParser(Parser):
+    """
+    Parse response references in the docstrings with rendered links to their
+    respective documentation.
+    """
+
+    _response_regex = re.compile(
+        r'(\s*):class:`(platypush\.message\.response\.(.+?))`', re.MULTILINE
+    )
+
+    @override
+    @classmethod
+    def parse(cls, docstring: str) -> str:
+        while True:
+            m = cls._response_regex.search(docstring)
+            if not m:
+                break
+
+            class_name = m.group(3).split('.')[-1]
+            package = '.'.join(m.group(3).split('.')[:-1])
+            docstring = cls._response_regex.sub(
+                f'{m.group(1)}`{class_name} '
+                f'<https://docs.platypush.tech/platypush/responses/{package}.html#{m.group(2)}>`_',
+                docstring,
+                count=1,
+            )
+
+        return docstring
--- a/Show more
+++ b/Show more
Author	SHA1	Message	Date
Fabio Manganiello	aaac6488d6	Updated webapp dist files	2023-05-22 02:24:24 +02:00
Fabio Manganiello	d7405ad05d	Added multiple parsers for the entities referenced in docstrings. The `inspect` plugin can now detect references to plugins, backends, events, responses and schemas in docstrings and replace them either with links to the documentation or auto-generated examples.	2023-05-22 02:20:58 +02:00