Docs: auto generate plugin schema reference (#1770)

Co-authored-by: Timur Olzhabayev <[email protected]>

Author: hugohaggmark

docusaurus/website/package.json

@@ -5,6 +5,7 @@
   "scripts": {
     "docusaurus": "docusaurus",
     "start": "docusaurus start",
+    "prebuild": "./scripts/download-schema.sh && ./scripts/generate-markdown.sh",
     "build": "docusaurus build",
     "swizzle": "docusaurus swizzle",
     "deploy": "docusaurus deploy",

docusaurus/website/scripts/download-schema.sh

@@ -0,0 +1,31 @@
+#!/bin/bash
+
+# Script to download the Grafana plugin schema JSON file
+# and store it locally in the same directory
+
+# Exit on error
+set -e
+
+# Define variables
+SCHEMA_URL="https://raw.githubusercontent.com/grafana/grafana/main/docs/sources/developers/plugins/plugin.schema.json"
+OUTPUT_FILE="$(dirname "$0")/plugin.schema.json"
+
+echo "Downloading Grafana plugin schema..."
+
+# Download the file
+if curl -s -f -o "$OUTPUT_FILE" "$SCHEMA_URL"; then
+    echo "Schema successfully downloaded to $OUTPUT_FILE"
+else
+    echo "Error: Failed to download schema from $SCHEMA_URL" >&2
+    exit 1
+fi
+
+# Verify the downloaded file
+if [ ! -s "$OUTPUT_FILE" ]; then
+    echo "Error: Downloaded file is empty" >&2
+    rm -f "$OUTPUT_FILE"
+    exit 1
+fi
+
+
+echo "Schema download complete!"

docusaurus/website/scripts/generate-markdown.sh

@@ -0,0 +1,49 @@
+#!/bin/bash
+
+# Script generate markdown files from the Grafana plugin schema JSON file
+
+# Exit on error
+set -e
+
+INPUT_FILE="$(dirname "$0")/plugin.schema.json"
+PARTIALS="$(dirname "$0")/partials"
+OUTPUT_FILE="$(dirname "$0")/../../docs/reference/metadata.md"
+
+# Verify the downloaded file
+if [ ! -s "$INPUT_FILE" ]; then
+    echo "Error: input schema doesn't exist or is empty" >&2
+    rm -f "$INPUT_FILE"
+    exit 1
+fi
+
+npx --yes jsonschema2mk --partials "$PARTIALS" --schema "$INPUT_FILE" > "$OUTPUT_FILE"
+
+# Detect OS and set sed options accordingly
+if [[ "$OSTYPE" == "darwin"* ]]; then
+    SED_OPTS="-i ''"
+else
+    SED_OPTS="-i"
+fi
+
+# Add docusaurus header to the top of the file
+sed $SED_OPTS "1i\\
+---\\
+id: plugin-json\\
+title: Metadata (plugin.json)\\
+description: Reference for the Grafana plugin.json metadata file.\\
+keywords:\\
+  - grafana\\
+  - plugins\\
+  - documentation\\
+  - plugin.json\\
+  - API reference\\
+  - API\\
+sidebar_position: 10\\
+---\\
+\\
+# Plugin metadata (plugin.json)
+" "$OUTPUT_FILE"
+
+rm -f "$INPUT_FILE"
+
+echo "Markdown generation complete!"

docusaurus/website/scripts/partials/element.md

@@ -0,0 +1,17 @@
+{{#if path~}}
+<a name="{{{tolink (or path 'root')}}}"></a>
+{{{mdlevel path}}}{{#if path}} {{escape path}}{{/if}}
+{{/if~}}
+{{#if (or description deprecated)}}
+
+{{#if deprecated}}(DEPRECATED) {{/if}}{{{description}}}
+
+{{/if}}
+
+{{> type . ~}}
+{{#each (get_examples .) ~}}
+{{> example ~}}
+{{/each ~}}
+{{#each (get_ref_items) ~}}
+{{>element . ~}}
+{{/each ~}}

docusaurus/website/scripts/partials/example.md

@@ -0,0 +1,41 @@
+{{#if (length properties) ~}}
+**{{prefix_text}}Properties**
+
+{{> object_property_header}}
+{{#each properties ~}}
+{{> object_property (jsmk_property . path=(pathjoinobj ../path @key .) parent=.. name=@key)}}
+{{/each}}
+
+{{/if}}
+{{#if (length patternProperties) ~}}
+**{{prefix_text}}Properties (Pattern)**
+
+{{> object_property_header}}
+{{#each patternProperties ~}}
+{{> object_property (jsmk_property . path=(pathjoinobj ../path @key .) parent=.. name=@key)}}
+{{/each}}
+
+{{/if}}
+
+{{#if (isdefined minProperties)}}
+**{{prefix_text}}Minimal Properties:** {{escape minProperties}}{{br}}
+{{/if~}}
+{{#if (isdefined maxProperties)}}
+**{{prefix_text}}Maximal Properties:** {{escape maxProperties}}{{br}}
+{{/if~}}
+{{#if (and (isdefined propertyNames) (isdefined propertyNames.pattern))}}
+**{{prefix_text}}Property Name Pattern:** {{code (escapeRegexp propertyNames.pattern)}}{{br}}
+{{/if~}}
+{{#if (isdefined dependentRequired)}}
+{{#each dependentRequired}}
+**{{prefix_text}}If property _{{@key}}_ is defined**, property/ies {{#each this}}_{{this}}_{{#unless @last}}, {{/unless}}{{/each}} is/are required.{{br}}
+{{/each}}
+{{/if~}}
+{{#if (isdefined dependentSchemas)}}
+{{#each dependentSchemas}}
+**{{prefix_text}}If property _{{@key}}_ is defined**:
+
+{{> element_part this type=(or type ../type) path=(pathjoin path (plus "dependentSchemas " @key))}}
+
+{{/each}}
+{{/if~}}

docusaurus/website/scripts/partials/object.md

@@ -0,0 +1,13 @@
+|
+{{~#mylink .}}**{{escape name}}**{{/mylink ~}}
+{{#if (and title (title_isnot_name .))}}<br/>({{escape title}}){{/if ~}}
+|
+{{~code display_type ~}}
+|
+{{~#if deprecated}}(DEPRECATED)<br/>{{/if}}
+{{~#if description ~}}
+{{firstline description .}}<br/>{{/if ~}}
+{{>extra_inline . ~}}
+|
+{{~#if (isdefined required)}}{{#if required}} ✅ {{/if}}{{/if~}}
+|

docusaurus/website/scripts/partials/object_property.md

@@ -0,0 +1,2 @@
+| Name | Type | Description | Required |
+| ---- | ---- | ----------- | :------: |

docusaurus/website/scripts/partials/object_property_header.md

@@ -0,0 +1,9 @@
+{{#if (is_type type "object") ~}}
+{{> object . ~}}
+{{~else~}}
+{{#if (is_type type "array") ~}}
+{{> array . ~}}
+{{~else~}}
+{{> simple ~}}
+{{/if ~}}
+{{/if ~}}