Repository: kestra-io/kestra
Issue: Adjust the plugin documentation to separate title and description, highlight deprecated properties and better handle custom definitions (now shown as FQCN)
Labels: enhancement

### Feature description

![image](https://github.com/kestra-io/kestra/assets/86264395/e70c65c0-00b3-4204-b483-7dc1ae4b8b78)


Issue comments:

Pull request review comments:

Patch that resolved the issue:
diff --git a/core/src/main/java/io/kestra/core/docs/JsonSchemaGenerator.java b/core/src/main/java/io/kestra/core/docs/JsonSchemaGenerator.java
index 484a628fbf..3f587b9fbe 100644
--- a/core/src/main/java/io/kestra/core/docs/JsonSchemaGenerator.java
+++ b/core/src/main/java/io/kestra/core/docs/JsonSchemaGenerator.java
@@ -252,6 +252,11 @@ public CustomDefinition provideCustomSchemaDefinition(ResolvedType javaType, Sch
             if (schema != null && schema.deprecated()) {
                 memberAttributes.put("$deprecated", true);
             }
+
+            Deprecated deprecated = member.getAnnotationConsideringFieldAndGetter(Deprecated.class);
+            if (deprecated != null) {
+                memberAttributes.put("$deprecated", true);
+            }
         });
 
         // Add Plugin annotation special docs
diff --git a/core/src/main/resources/docs/macro.peb b/core/src/main/resources/docs/macro.peb
index 7d6d9102cd..5129d5f21e 100644
--- a/core/src/main/resources/docs/macro.peb
+++ b/core/src/main/resources/docs/macro.peb
@@ -1,6 +1,6 @@
 {% macro type(data) %}
     {%- if data['$ref'] -%}
-    [=={{- data['$ref'] | slice(8) -}}==](#{{- data['$ref'] | slice(8) | lower -}})
+    [=={{- data['$ref'] | slice(8) | substringAfterLast('.') -}}==](#{{- data['$ref'] | slice(8) | lower -}})
     {%- else -%}
     =={{- data.type -}}==
     {%- endif -%}
@@ -87,17 +87,16 @@
 * **Possible Values:**
     {%- for current in data.enum %}
   * `{{current}}`
-    {%- endfor -%}
-{%- endif -%}
+    {%- endfor %}
+{% endif -%}
 
 {%- if data.title %}
-> {{ data.title }}
-{%- endif -%}
+**{{ data.title }}**
+{% endif -%}
 
 {%- if data.description %}
-{{ data.description }}
-{%- endif -%}
-
+> {{ data.description }}
+{%- endif %}
 {% endmacro %}
 
 
diff --git a/core/src/main/resources/docs/task.peb b/core/src/main/resources/docs/task.peb
index ee7cdcca22..4e286fed16 100644
--- a/core/src/main/resources/docs/task.peb
+++ b/core/src/main/resources/docs/task.peb
@@ -28,10 +28,12 @@ type: "{{ cls }}"
 ```
 
 {% if docDescription -%}
-> {{ docDescription }}
+<span style="font-size:1.5em;">{{ docDescription }}</span>
 {%- endif %}
 
-{{ docBody }}
+{% if docBody -%}
+  {{ docBody }}
+{%- endif %}
 
 {% if docExamples != null %}
 ## Examples


Test patch:
diff --git a/cli/src/test/java/io/kestra/cli/commands/plugins/PluginDocCommandTest.java b/cli/src/test/java/io/kestra/cli/commands/plugins/PluginDocCommandTest.java
index d18fd242cb..d9a20c2022 100644
--- a/cli/src/test/java/io/kestra/cli/commands/plugins/PluginDocCommandTest.java
+++ b/cli/src/test/java/io/kestra/cli/commands/plugins/PluginDocCommandTest.java
@@ -101,14 +101,14 @@ void run() throws IOException, URISyntaxException {
                 * **Dynamic:** ✔️
                 * **Required:** ❌
 
-                > Example interface
+                **Example interface**
                 """));
             assertThat(taskDoc, containsString("""
                 ### `from`
                 * **Type:**
                   * ==string==
                   * ==array==
-                  * [==io.kestra.core.models.annotations.Example==](#io.kestra.core.models.annotations.example)
+                  * [==Example==](#io.kestra.core.models.annotations.example)
                 * **Dynamic:** ✔️
                 * **Required:** ✔️
                 """));
diff --git a/core/src/test/java/io/kestra/core/docs/JsonSchemaGeneratorTest.java b/core/src/test/java/io/kestra/core/docs/JsonSchemaGeneratorTest.java
index 489987f630..dc9ea23785 100644
--- a/core/src/test/java/io/kestra/core/docs/JsonSchemaGeneratorTest.java
+++ b/core/src/test/java/io/kestra/core/docs/JsonSchemaGeneratorTest.java
@@ -96,6 +96,10 @@ void flow() throws URISyntaxException {
 
             var bashType = definitions.get("io.kestra.core.tasks.log.Log-2");
             assertThat(bashType, is(notNullValue()));
+
+            var properties = (Map<String, Map<String, Object>>) flow.get("properties");
+            var listeners = properties.get("listeners");
+            assertThat(listeners.get("$deprecated"), is(true));
         });
     }