@grafana/create-plugin 7.15.0 → 7.16.0

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

@@ -4,10 +4,14 @@ description: "Worked examples of the {{{yamlEscape pluginName}}} panel."
 sidebar_position: 4
 ---
 
+<!-- snippet:use-example-json -->
+
 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**.
 
+<!-- /snippet:use-example-json -->
+
 <!-- 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.
+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. Only use a screenshot that the example's JSON produces: open the image and check that what it shows, such as the legend, the values and the number of series, matches the JSON. If no image matches, leave the example without one and flag it. Don't cut settings from an excerpt that its result depends on, such as some of the overrides behind a screenshot.
 
 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.
 -->

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

@@ -22,7 +22,7 @@ Fill this in: Emit a markdown table with these columns - one row per option regi
 
 - _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.
+- _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. When the default matches none of the values the option offers, such as a different case, give what the panel actually does with it.
 - _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.