@grafana/create-plugin 7.13.0 → 7.14.0

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.