@grafana/create-plugin 7.13.0 → 7.15.0

package/templates/docs/datasource/docs/troubleshooting.md

@@ -0,0 +1,73 @@
+---
+title: Troubleshooting
+description: "Troubleshoot common {{{yamlEscape pluginName}}} connection, authentication and query errors."
+keywords:
+  - "{{{yamlEscape pluginName}}}"
+  - data source
+  - troubleshooting
+sidebar_position: 8
+---
+
+This page explains how to fix common issues when you configure or use the {{{pluginName}}} data source. For setup instructions, refer to [Configure the {{{pluginName}}} data source](./configure.md).
+
+<!-- section-brief
+Fill this in: Never guess failures. Each symptom must come from an error message in source, a known issue in the README or other docs or a reported issue.
+
+Replace this brief with one H2 per category that has real failures, in this order:
+
+- `## Connection errors`: Grafana can't reach the service, such as timeouts or TLS errors.
+- `## Authentication errors`: wrong credentials, expired tokens or missing permissions.
+- `## Query errors`: queries that fail or return no data.
+- `## Template variable errors`: variables that return no or wrong values, or load slowly.
+{{#if hasAnnotations}}
+- `## Annotation errors`: annotations that don't appear, linking to [annotations](./annotations.md).
+{{/if}}
+{{#if hasAlerting}}
+- `## Alerting errors`: alert rules that fail or don't fire, such as a query that works on a dashboard but not in an alert rule, which skips the frontend data source class. Link to [alerting](./alerting.md).
+{{/if}}
+{{#if hasBackend}}
+- `## Private data source connect errors`: connections through PDC that fail, if the backend supports the secure SOCKS proxy.
+{{/if}}
+- `## Performance issues`: slow dashboards, timeouts or rate limits, and the settings that help.
+
+Add an H2 if the backend classifies its errors, or for another feature with real failures, such as ad hoc filters.
+
+Open each H2 with one sentence on when its errors occur. Add an H3 per symptom, named after the error message in quotes, such as `### "Password authentication failed"`, then **Symptoms:** and a **Possible causes and solutions:** table, or a numbered **Solutions:** list for a single cause.
+-->
+
+## Get more detail about an error
+
+To see the raw request and response for a panel, open the panel editor and click **Query inspector**.
+{{#if hasBackend}}
+
+In self-managed Grafana, you can also find more detail in the Grafana server logs:
+
+1. Set the log level to `debug` in the Grafana configuration file:
+
+   ```ini
+   [log]
+   level = debug
+   ```
+
+1. Restart Grafana and reproduce the error.
+1. Look for log lines with `logger=plugin.{{{pluginId}}}`.
+1. Set the log level back to `info` when you're done, to keep the logs small.
+{{/if}}
+
+## Get additional help
+
+If this page doesn't solve your problem:
+
+- Search the [Grafana community forums](https://community.grafana.com/).
+- If your Grafana Cloud or Grafana Enterprise plan includes support, contact Grafana Support.
+
+<!-- section-brief
+Fill this in: Add links to the plugin's issue tracker and the service's docs to the list above.
+-->
+
+When you report an issue, include:
+
+- The Grafana and plugin versions.
+- The error message, with sensitive information removed.
+- The steps to reproduce the issue.
+- The relevant data source settings, with credentials removed.

package/templates/docs/panel/docs/AGENTS.md

@@ -0,0 +1,113 @@
+# Plugin docs
+
+This folder is the documentation for **{{{pluginName}}}**, published at
+`grafana.com/grafana/plugins/{{pluginId}}/docs/`.
+
+## Guides
+
+Read these before you write or change any page. This docs format is new and your training
+data does not cover it, so do not rely on what you know about other docs tools.
+
+Run `{{packageManagerName}} run docs:validate` and open the guide on its last line, `Docs guides:`. It's
+the guides' `index.md`, which says which guide to read for what, and the other guides sit next to it.
+The guides match the version of the validator this plugin uses. The line is a local path, usually
+`node_modules/@grafana/plugin-docs-cli/docs/index.md`, or a URL when the package isn't on disk, such as
+with Yarn Plug'n'Play.
+
+The guides name scripts such as `docs:validate`. This plugin uses **{{packageManagerName}}**, so run them
+with `{{packageManagerName}} run`, as in the commands below.
+
+## Pages and their source
+
+When you change code, update the page that documents it:
+
+| Page                 | Source of truth                                                                        |
+| -------------------- | -------------------------------------------------------------------------------------- |
+| `index.md`           | Nothing - it is a curated router. Update it when pages are added or removed.           |
+| `options.md`         | `setPanelOptions` and `useFieldConfig` in `src/module.ts`                              |
+| `data-formats.md`    | The panel component's data handling, plus any field pickers in `src/module.ts`         |
+| `examples.md`        | `provisioning/dashboards/*.json` if present, otherwise the panel's own option defaults |
+| `troubleshooting.md` | Error and empty-state messages in source, known and reported issues. Never guess.      |
+
+Never guess failures in `troubleshooting.md`. Each symptom must come from an error, warning or empty-state
+message in source, a known issue in the README or other docs or a reported issue.
+
+## Optional pages
+
+Add one of these pages when the plugin has the matching feature. Use the filename given here, give the page
+a `sidebar_position` that puts it where it belongs and link it from `index.md`.
+
+| Trigger                                                                            | Page               | Scope                                                        |
+| ---------------------------------------------------------------------------------- | ------------------ | ------------------------------------------------------------ |
+| `setPresetsSupplier(...)` in source                                                | `presets.md`       | The presets the panel ships, when each applies, screenshots. |
+| RBAC role declarations in `src/plugin.json`                                        | `permissions.md`   | What each role grants, default assignments.                  |
+| Substantial accessibility considerations (keyboard shortcuts, screen reader notes) | `accessibility.md` | Keyboard interaction, ARIA, contrast, motion preferences.    |
+
+## What not to write
+
+Never write installation instructions, such as installing the plugin with `grafana-cli`, from a zip file or
+in Docker. The Installation tab on the plugin page covers them, and these docs start from a plugin that is
+already installed. When the README has an installation section, leave it out of the pages.
+
+## Section briefs
+
+Each section of a scaffolded page has a brief telling you what belongs there. A brief is an HTML comment
+that starts with `section-brief`. Search the docs folder for `section-brief` to find what is left to write:
+
+```markdown
+## Options
+
+<!-- section-brief
+Fill this in: Describe every option the plugin registers, one row per option.
+
+If the plugin has no options, remove this section entirely.
+-->
+```
+
+Some sections also have fixed text, with a brief that builds on it:
+
+```markdown
+## Basic example
+
+A panel excerpt in dashboard JSON has this shape:
+
+<!-- section-brief
+Fill this in: Complete the excerpt above with the options the example needs.
+-->
+```
+
+Text outside a brief is written for every panel and is part of the scaffold. Keep it, and change it
+only where it's wrong for this plugin, such as a menu path or a step that differs.
+
+Everything inside a brief is the instruction. A brief covers the section it sits under, unless it says
+otherwise: it may tell you to extend the fixed text above it, to replace it with several sections or to
+remove the page. When a brief says to remove a section, remove its heading and fixed text too.
+
+To fill a section:
+
+1. Read the brief.
+2. Read the source the page documents, from the table above, then write the section.
+3. Delete the whole comment, from `<!-- section-brief` to `-->`.
+
+Briefs are not shown in the preview or the catalog, so a section you haven't written looks like a bare
+heading. `docs:validate` lists every section that still has only its brief.
+
+## Validate
+
+```bash
+{{packageManagerName}} run docs:validate
+```
+
+Run `docs:validate` after every page you write or change and fix what it reports. A docs task is done when
+it reports no warnings and no suggestions about section briefs. In particular, an `empty-section` or
+`unfilled-section-brief` suggestion means a section is still unwritten or a brief is still in place. Neither
+fails validation, so a passing exit code alone does not mean the docs are done.
+
+## Preview
+
+```bash
+{{packageManagerName}} run docs:serve    # local preview at http://localhost:3001, reloads on save
+```
+
+`docs:serve` keeps running until you stop it. Start it in the background if you need to look at the
+rendered pages, and stop it when you are done.

package/templates/docs/panel/docs/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

package/templates/docs/panel/docs/README.md

@@ -0,0 +1,20 @@
+# {{{pluginName}}} documentation
+
+This folder is the documentation for **{{{pluginName}}}**. It's published on the Documentation tab of
+`grafana.com/grafana/plugins/{{pluginId}}/` with each plugin release. This README isn't published.
+
+To learn how plugin docs work and how to write them, read the
+[Add documentation to your plugin](https://grafana.com/developers/plugin-tools/how-to-guides/plugin-docs) guide.
+
+## Next steps
+
+1. Write the pages. Each section has a note that says what belongs there. **Or** let an AI agent draft them from your source code and README: commit your changes, then run `{{createPluginCmd}} add docs-content`. Review its work either way.
+2. Add screenshots, videos and figures where they help readers. Save them inside this folder, for example in `img/`, and link to them with a relative path. `docs:validate` checks their formats and sizes.
+3. Run `{{packageManagerName}} run docs:serve` to preview the docs. It also lists every section left to fill.
+
+## Commands
+
+```bash
+{{packageManagerName}} run docs:serve     # local preview at http://localhost:3001
+{{packageManagerName}} run docs:validate  # check your docs, including sections left to fill
+```

package/templates/docs/panel/docs/data-formats.md

@@ -0,0 +1,27 @@
+---
+title: Data formats
+description: "Learn what data formats the {{{yamlEscape pluginName}}} panel accepts."
+sidebar_position: 2
+---
+
+This document explains the data the {{{pluginName}}} panel needs from a query, so you can build a matching query or check your test data.
+
+## Supported data shape
+
+<!-- section-brief
+Fill this in: Describe the data frame shape {{{pluginName}}} expects: time series with N numeric fields, table with specific columns, single numeric value, geographic coordinates, log lines, etc. Be specific about field types and structure, because this is the contract dashboard authors rely on when building queries for the panel. Name the required field types (time, number, string, boolean) and any minimum/maximum field counts. After each shape, add a `#### Example` table whose headers are the field names the panel reads, with 3-5 rows of realistic values, so a reader can build a matching query or test data.
+-->
+
+## Field mapping
+
+<!-- section-brief
+Fill this in: Explain which incoming field plays which role in the visualization - for example "the first time-typed field is the x-axis, all numeric fields become series". If {{{pluginName}}} lets users explicitly pick field roles in the editor, document those controls here. Remove the section if mapping is fully automatic and not user-configurable.
+-->
+
+## Check what your query returns
+
+To see the data the panel receives, open the panel editor, click **Query inspector** and select the **Data** tab. You can also turn on **Table view** at the top of the panel editor to see the data as a table.
+
+## Reshape data that doesn't match
+
+If a query returns data in a different shape, you can reshape it without changing the query. Select the **Transform data** tab in the panel editor and add a transformation. For more information, refer to [Transform data](https://grafana.com/docs/grafana/latest/panels-visualizations/query-transform-data/transform-data/).

package/templates/docs/panel/docs/examples.md

@@ -0,0 +1,35 @@
+---
+title: Examples
+description: "Worked examples of the {{{yamlEscape pluginName}}} panel."
+sidebar_position: 4
+---
+
+To use an example, open your dashboard and go to **Dashboard settings** > **JSON Model**. Paste the excerpt into the `panels` array and click **Save changes**.
+
+<!-- section-brief
+Fill this in: Show concrete examples of {{{pluginName}}} configured for real use cases. When the repo has panels of this plugin's type in `provisioning/dashboards/*.json`, take the examples from those before inventing any. Express each example as a `dashboard.json` panel excerpt: `type` and `options`, plus `fieldConfig` and `targets` when the example depends on them. Leave out `id`, `gridPos`, `pluginVersion`, datasource UIDs and timestamps - they are specific to one dashboard and hide the settings that matter. Pair each example with a screenshot of the rendered visualization.
+
+If the repo ships a complete dashboard, for example under `provisioning/dashboards/`, link to it for readers who want the full JSON. Use the file's `https://` URL in your repository - relative links can't point outside the docs folder.
+-->
+
+## Basic example
+
+A panel excerpt in dashboard JSON has this shape:
+
+```json
+{
+  "type": "{{pluginId}}",
+  "options": {},
+  "targets": []
+}
+```
+
+<!-- section-brief
+Fill this in: Complete the excerpt above as the minimum viable {{{pluginName}}} configuration: the smallest `panels[]` entry that produces a meaningful visualization. Include only the settings it needs, plus a sample query in `targets` if the panel reads data. If the panel doesn't read data, remove `targets` from the excerpt. Pair with a screenshot of the result.
+-->
+
+## Common variations
+
+<!-- section-brief
+Fill this in: Show 1-3 alternate configurations that cover the most common ways dashboard authors use {{{pluginName}}} - different data shapes, option combinations, or display modes. Each variation is an excerpt showing only the settings that differ from the basic example, plus a screenshot. Explain in one line what each variation demonstrates.
+-->

package/templates/docs/panel/docs/index.md

@@ -0,0 +1,26 @@
+---
+title: Introduction
+description: "Where to start and what to read next in the {{{yamlEscape pluginName}}} docs."
+sidebar_position: 1
+---
+
+<!-- section-brief
+Fill this in: Write a short orientation for someone who already has {{{pluginName}}} installed and landed here from the Documentation tab. One or two sentences on what this section covers and how it's organized. Do not restate what the plugin does, its feature list, or its requirements - that's the README's job on the Overview tab, and this reader has already seen it there. Do not list every page in this folder either - the sidebar already does that; use prose to say what to read first and why.
+-->
+
+## Recommended path
+
+<!-- section-brief
+Fill this in: Give a short, ordered reading path for someone new to {{{pluginName}}} - two or three sentences, not a repeat of the sidebar. Point out the one or two pages most people need first and why, e.g. "Start with **Data formats** to shape your query results, then **Options** to configure the panel."
+-->
+
+## Common tasks
+
+- [Shape your query results for {{{pluginName}}}](./data-formats.md)
+- [Configure panel and field options](./options.md)
+- [See worked dashboard.json examples](./examples.md)
+- [Fix a panel that isn't rendering correctly](./troubleshooting.md)
+
+<!-- section-brief
+Fill this in: Keep the list above and adapt it to {{{pluginName}}}'s actual entry points - add, remove or reword tasks so each one matches a real job a user comes here to do. If you remove a page, remove its task too. This is a curated set of jobs, not a mechanical list of every file in this folder.
+-->

package/templates/docs/panel/docs/options.md

@@ -0,0 +1,53 @@
+---
+title: Options
+description: "Reference for {{{yamlEscape pluginName}}} panel options."
+sidebar_position: 3
+---
+
+To change these options, edit the panel and use the options pane.
+
+<!-- section-brief
+Fill this in: Reference the options {{{pluginName}}} exposes in the panel editor. Cover both the custom options the panel adds (via `setPanelOptions` in source) and the standard field options it enables (via `useFieldConfig`). Skip the sections below that don't apply to this panel - if there's no Standard field options block, no Tooltip and legend section etc., remove those headings entirely rather than leaving an empty brief.
+
+Do not redocument the framework-level standard options themselves (Min, Max, Unit, etc.) - Grafana's own docs cover those. The Standard field options section lists which ones are enabled, nothing more.
+-->
+
+## Panel options
+
+<!-- section-brief
+Fill this in: Emit a markdown table with these columns - one row per option registered through `setPanelOptions` in `src/module.ts`. Match the Grafana built-in panel docs style: https://grafana.com/docs/grafana/latest/visualizations/panels-visualizations/visualizations/logs/#logs-options
+
+| Option | Type | Default | Description |
+| ------ | ---- | ------- | ----------- |
+
+- _Option_: the `name` value from the `setPanelOptions` `.add*({...})` call, verbatim.
+- _Type_: a short label for the editor the option uses, derived from the builder method (`addBooleanSwitch` → Toggle, `addSelect` → Select, `addNumberInput` → Number, `addFieldNamePicker` → Field picker). For a custom editor, name what it is, such as Color picker, rather than writing Custom.
+- _Default_: the value a reader sees in the panel editor, rendered as inline code. Resolve enum members, constants and translation calls to that value - `ClockMode.time` becomes `Time`. Keep the source expression only when it can't be resolved. When there is no default but the code falls back to a value while the option is unset, give that fallback value. Leave the cell empty only when there is neither.
+- _Description_: the `description` value, verbatim. If the verbatim text causes a `docs:validate` warning, reword it as little as possible and keep its meaning. When source has none, write one short sentence describing what the option does, based on how the panel code uses it. Don't guess beyond what the code shows.
+
+If the panel does not call `setPanelOptions`, remove this section entirely.
+-->
+
+## Standard field options
+
+For what each standard option does, refer to [Configure standard options](https://grafana.com/docs/grafana/latest/panels-visualizations/configure-standard-options/).
+
+<!-- section-brief
+Fill this in: A bulleted list of the standard field options this panel enables - the entries from `useFieldConfig({ standardOptions: [...] })` in `src/module.ts`. If the panel calls `useFieldConfig()` or `useFieldConfig({})` without a `standardOptions` key, document this as "all standard options are enabled" and list the standard set.
+
+If the panel does not call `useFieldConfig` at all, remove this section entirely, including the link above.
+-->
+
+## Custom field options
+
+<!-- section-brief
+Fill this in: A table with the same shape as Panel options (Option / Type / Default / Description) but for the per-field overrides registered via `useFieldConfig({ useCustomConfig: builder => ... })`. These appear under the Overrides picker in the panel editor.
+
+If the panel does not register custom field options, remove this section entirely.
+-->
+
+## Tooltip and legend options
+
+<!-- section-brief
+Fill this in: Describe the tooltip and legend options {{{pluginName}}} exposes: hover behavior, the fields the tooltip shows and its formatting, and legend placement, values and calculations. Most of these already appear in the Panel options table above when they're registered via `setPanelOptions` with `category: ['Tooltip']` or `category: ['Legend']`, so use this section only for narrative context that doesn't fit in a table row. Remove this section if there is nothing extra to say beyond the table.
+-->

package/templates/docs/panel/docs/troubleshooting.md

@@ -0,0 +1,35 @@
+---
+title: Troubleshooting
+description: "Troubleshoot the {{{yamlEscape pluginName}}} panel."
+sidebar_position: 5
+---
+
+This page explains how to fix common issues when you use the {{{pluginName}}} panel. For the data the panel expects, refer to [Data formats](./data-formats.md).
+
+<!-- section-brief
+Fill this in: Replace this brief with one H2 per real failure mode, such as "Panel shows no data", "Wrong field selected" or "Rendering errors". Open each H2 with the symptom users see, then give the most likely cause and the steps to resolve it. Remove this brief and add nothing if there are no real failures to report.
+-->
+
+## Get more detail about an error
+
+To see the data the panel receives, open the panel editor, click **Query inspector** and select the **Data** tab.
+
+For errors in the panel itself, open the developer tools in your browser and check the console.
+
+## Get additional help
+
+If this page doesn't solve your problem:
+
+- Search the [Grafana community forums](https://community.grafana.com/).
+- If your Grafana Cloud or Grafana Enterprise plan includes support, contact Grafana Support.
+
+<!-- section-brief
+Fill this in: Add links to the plugin's issue tracker to the list above.
+-->
+
+When you report an issue, include:
+
+- The Grafana and plugin versions.
+- The error message, with sensitive information removed.
+- The steps to reproduce the issue.
+- The panel options and a sample of the data it shows, with sensitive information removed.