From 8b23d1b2de244ba248c2786f20b607f1fc0b7f80 Mon Sep 17 00:00:00 2001 From: Levente Balogh Date: Wed, 28 Aug 2024 05:32:42 +0200 Subject: [PATCH] Docs: Update the "Prompts" page (#1042) Co-authored-by: Jack Westbrook Co-authored-by: Joe Perez --- docusaurus/docs/get-started/get-started.mdx | 5 +- .../docs/key-concepts/plugin-types-usage.md | 2 +- .../update-create-plugin-versions.mdx | 30 ---- docusaurus/docs/reference/cli-commands.md | 61 -------- docusaurus/docs/reference/cli-commands.mdx | 139 ++++++++++++++++++ docusaurus/docs/reference/prompts.md | 70 --------- .../snippets/createplugin-update-force.npm.md | 3 + .../createplugin-update-force.pnpm.md | 3 + .../createplugin-update-force.yarn.md | 3 + docusaurus/website/docusaurus.config.base.js | 8 + 10 files changed, 158 insertions(+), 166 deletions(-) delete mode 100644 docusaurus/docs/migration-guides/update-create-plugin-versions.mdx delete mode 100644 docusaurus/docs/reference/cli-commands.md create mode 100644 docusaurus/docs/reference/cli-commands.mdx delete mode 100644 docusaurus/docs/reference/prompts.md create mode 100644 docusaurus/docs/snippets/createplugin-update-force.npm.md create mode 100644 docusaurus/docs/snippets/createplugin-update-force.pnpm.md create mode 100644 docusaurus/docs/snippets/createplugin-update-force.yarn.md diff --git a/docusaurus/docs/get-started/get-started.mdx b/docusaurus/docs/get-started/get-started.mdx index 482ab5823..51733a1ed 100644 --- a/docusaurus/docs/get-started/get-started.mdx +++ b/docusaurus/docs/get-started/get-started.mdx @@ -117,7 +117,7 @@ Run the following command and answer the prompts: queryString="current-package-manager" /> -For help with the prompts, refer to the [Prompts reference](../reference/prompts.md). +For help with the prompts, refer to the [CLI commands](../reference/cli-commands.mdx). ### Open the generated folder structure @@ -266,6 +266,3 @@ Congratulations! You've just scaffolded your first plugin which you can now acce - Learn how to [extend](/how-to-guides) its functionality. - Review the [plugin examples](https://github.com/grafana/grafana-plugin-examples) to learn about good practices. - Learn how to [package](/publish-a-plugin/package-a-plugin), [sign](/publish-a-plugin/sign-a-plugin), and [publish](/publish-a-plugin/publish-or-update-a-plugin.md) your plugin to the Grafana [plugin catalog](https://grafana.com/plugins). - -## See also -For a complete list of available CLI commands, refer to the [CLI reference](/reference/cli-commands.md). diff --git a/docusaurus/docs/key-concepts/plugin-types-usage.md b/docusaurus/docs/key-concepts/plugin-types-usage.md index fb728a04e..06bfa74f8 100644 --- a/docusaurus/docs/key-concepts/plugin-types-usage.md +++ b/docusaurus/docs/key-concepts/plugin-types-usage.md @@ -30,7 +30,7 @@ Grafana plugin development allows for many options depending on the type of user - **Data-source plugin** - a connection to a new database or other source of data. - **App plugin** - an integrated out-of-the-box experience. -Refer to [Get started](../get-started/get-started.mdx) for instructions on how to quickly scaffold [each type](../reference/prompts.md#select-a-plugin-type) of plugin. +Refer to [Get started](../get-started/get-started.mdx) for instructions on how to quickly scaffold [each type](../reference/cli-commands.mdx#select-a-plugin-type) of plugin. :::note diff --git a/docusaurus/docs/migration-guides/update-create-plugin-versions.mdx b/docusaurus/docs/migration-guides/update-create-plugin-versions.mdx deleted file mode 100644 index ead0f56ed..000000000 --- a/docusaurus/docs/migration-guides/update-create-plugin-versions.mdx +++ /dev/null @@ -1,30 +0,0 @@ ---- -id: update-create-plugin-versions -title: Update create-plugin versions -sidebar_position: 20 -description: How to update existing plugin create-plugin tool to a newer version. -keywords: - - grafana - - plugins - - plugin - - create-plugin - - migrating ---- - -import UpdateNPM from '@snippets/createplugin-update.npm.md'; -import UpdatePNPM from '@snippets/createplugin-update.pnpm.md'; -import UpdateYarn from '@snippets/createplugin-update.yarn.md'; - -To update an existing plugin to use a newer version of the `create-plugin` tool, run the following command: - - - -This command reruns the original scaffolding commands against the configuration files, dependencies, and scripts. It automatically uses the latest version of the `create-plugin` tool. diff --git a/docusaurus/docs/reference/cli-commands.md b/docusaurus/docs/reference/cli-commands.md deleted file mode 100644 index aa194687e..000000000 --- a/docusaurus/docs/reference/cli-commands.md +++ /dev/null @@ -1,61 +0,0 @@ ---- -id: cli-commands -title: CLI commands -description: Reference for CLI commands of the create-plugin tool. -keywords: - - grafana - - plugins - - plugin - - create-plugin - - prompts - - CLI -sidebar_position: 20 ---- - -# CLI commands - -Use the CLI for essential tasks of plugin development, substituting `npm` for `pnpm`, or `yarn` based on your choice of package manager. - -### `npm run build` - -Compiles and bundles the project using Webpack in production mode. - -### `npm run dev` - -Runs Webpack in watch mode for development, continually monitoring for changes. - -### `npm run e2e` - -Runs Grafana end-to-end tests using Cypress. - -### `npm run e2e:update` - -Runs Grafana end-to-end tests and tests any test screenshots, using Cypress. - -### `npm run lint` - -Lints the frontend codebase using ESLint with the `.gitignore` file to ignore certain files. Results are cached locally to speed up future linting tasks. - -### `npm run lint:fix` - -Lints the frontend codebase using ESLint and automatically fixes detected issues. - -### `npm run typecheck` - -Performs a type-checking process on the frontend code using TypeScript. - -### `npm run server` - -Launches the [Grafana development server](/get-started/set-up-development-environment) using Docker. - -### `npm run sign` - -Signs the Grafana plugin using the latest version of `@grafana/sign-plugin`. - -### `npm run test` - -Executes frontend tests, running only the tests that have changed, and enables a watch mode for ongoing testing. - -### `npm run test:ci` - -Runs frontend tests for CI, ensuring it passes even with no tests, and utilizes a maximum of four workers for parallel execution. diff --git a/docusaurus/docs/reference/cli-commands.mdx b/docusaurus/docs/reference/cli-commands.mdx new file mode 100644 index 000000000..baf05f85c --- /dev/null +++ b/docusaurus/docs/reference/cli-commands.mdx @@ -0,0 +1,139 @@ +--- +id: cli-commands +title: CLI commands +description: Reference for commands available in the create-plugin tool. +keywords: + - grafana + - plugins + - plugin + - create-plugin + - prompts + - commands +sidebar_position: 40 +--- + +import ScaffoldNPM from '@snippets/createplugin-scaffold.npm.md'; +import ScaffoldPNPM from '@snippets/createplugin-scaffold.pnpm.md'; +import ScaffoldYarn from '@snippets/createplugin-scaffold.yarn.md'; +import UpdateNPM from '@snippets/createplugin-update.npm.md'; +import UpdatePNPM from '@snippets/createplugin-update.pnpm.md'; +import UpdateYarn from '@snippets/createplugin-update.yarn.md'; +import UpdateForceNPM from '@snippets/createplugin-update-force.npm.md'; +import UpdateForcePNPM from '@snippets/createplugin-update-force.pnpm.md'; +import UpdateForceYarn from '@snippets/createplugin-update-force.yarn.md'; + +# CLI commands + +Below you can find the available commands in `@grafana/create-plugin`. + +## create-plugin + +Use the `create-plugin` command to scaffold your plugin. + + + + +When running the `create-plugin` command, the following prompts appear: + +### Select a plugin type + +``` +? Select a plugin type … +❯ App (add custom pages, UI extensions and bundle other plugins) + Data source (query data from a custom source) + Panel (add a visualization for data or a widget) + App with Scenes (create dynamic dashboards in app pages) +``` + +To learn more about the various types of plugins, refer to [Grafana plugin types and usage](../key-concepts/plugin-types-usage.md). + +For more information on how Scenes allows you to create dashboard-like experiences in app plugins, see the [Scenes](https://grafana.com/developers/scenes) documentation. + +### Add a backend to support server-side functionality? (y/N) + +If you are creating an app or a data source plugin, you will be asked whether to additionally add a backend component. + +Backend plugins offer powerful features such as: + +- Enable [Grafana Alerting](https://grafana.com/docs/grafana/latest/alerting/) for data sources. +- Connect to non-HTTP services to which a browser normally can’t connect. For example, SQL database servers. +- Keep state between users. For example, query caching for data sources. +- Use custom authentication methods and/or authorization checks that aren’t supported in Grafana. +- Use a custom data source request proxy. + +To learn more, refer to [Backend plugins](../key-concepts/backend-plugins/index.md). + +### Enter a name for your plugin + +Give your plugin a name which helps identify its purpose. + +### Enter your organization name (usually your Grafana Cloud org) + +Enter the name of your organization. This must be your [Grafana Cloud](https://grafana.com/signup/) organization. With the organization name you can [sign](../publish-a-plugin/sign-a-plugin.md) and optionally [publish](../publish-a-plugin/publish-or-update-a-plugin.md) the plugin to the [Grafana plugin catalog](https://grafana.com/grafana/plugins). + +### Bypass prompts + +You can bypass all the preceding prompts by using `create-plugin` CLI arguments. +To scaffold a plugin with the CLI arguments, pass them to the `create-plugin` command like so: + +``` +npx @grafana/create-plugin \ + --plugin-type="app" \ + --plugin-name="myPlugin" \ + --org-name="myorg" \ + --backend +``` + +You can scaffold plugins using CLI arguments to get started faster. Using arguments also allows you to run the tool in a non-interactive environment such as CI or to scaffold plugins with other tooling. + +Refer to the following table for the full list of prompt bypass options: + +| Prompt | Equivalent Argument Name | Values | +| ---------------- | ---------------------------- | -------------------------------------------------- | +| **Plugin type** | `--plugin-type` | one of `app`, `datasource`, `panel` or `scenesapp` | +| **Backend** | `--backend` / `--no-backend` | boolean | +| **Name** | `--plugin-name` | string | +| **Organization** | `--org-name` | string | + + +## update + +To update an existing plugin to use the latest version of the `create-plugin` tool, run the following command from your plugin's root directory: + + + +This command updates the following: +* **`/.config`** - configuration files for building a plugin +* **NPM dependencies** - dependencies (mostly used for supporting latest Grafana versions and build updates) +* **NPM scripts** - any updates in build-related scripts + +### update --force + +By default, the `update` command will stop if there are any uncommitted changes in the repository. If you want to force the update, you can use the `--force` flag: + + + diff --git a/docusaurus/docs/reference/prompts.md b/docusaurus/docs/reference/prompts.md deleted file mode 100644 index 9d634551b..000000000 --- a/docusaurus/docs/reference/prompts.md +++ /dev/null @@ -1,70 +0,0 @@ ---- -id: prompts -title: Prompts -description: Reference for prompts of the create-plugin tool. -keywords: - - grafana - - plugins - - plugin - - create-plugin - - prompts -sidebar_position: 40 ---- - -# Prompts - -When running the `create-plugin` command, the following prompts appear. - -### Select a plugin type - -Select the type of plugin you would like to create: - -- App (add custom pages, UI extensions and bundle other plugins) -- Data source (query data from a custom source) -- Panel (add a visualization for data or a widget) -- App with Scenes (create dynamic dashboards in app pages) - -To learn more about the various types of plugins, refer to [Grafana plugin types and usage](../key-concepts/plugin-types-usage.md). - -For more information on how Scenes allows you to create dashboard-like experiences in app plugins, see the [Scenes](https://grafana.com/developers/scenes) documentation. - -### Add a backend to support server-side functionality? (y/N) - -If you are creating an app or a data source plugin, you will be asked whether to additionally add a backend component. - -Backend plugins offer powerful features such as: - -- Enable [Grafana Alerting](https://grafana.com/docs/grafana/latest/alerting/) for data sources. -- Connect to non-HTTP services to which a browser normally can’t connect. For example, SQL database servers. -- Keep state between users. For example, query caching for data sources. -- Use custom authentication methods and/or authorization checks that aren’t supported in Grafana. -- Use a custom data source request proxy. - -To learn more, refer to [Backend plugins](../key-concepts/backend-plugins/index.md). - -### Enter a name for your plugin - -Give your plugin a name which helps identify its purpose. - -### Enter your organization name (usually your Grafana Cloud org) - -Enter the name of your organization. This must be your [Grafana Cloud](https://grafana.com/signup/) organization. With the organization name you can [sign](../publish-a-plugin/sign-a-plugin.md) and optionally [publish](../publish-a-plugin/publish-or-update-a-plugin.md) the plugin to the [Grafana plugin catalog](https://grafana.com/grafana/plugins). - -## Bypass prompts - -You can bypass all the preceding prompts by using `create-plugin` CLI arguments. To scaffold a plugin with the CLI arguments, pass them to the `create-plugin` command like so: - -``` -npx @grafana/create-plugin --plugin-type="app" --plugin-name="myPlugin" --org-name="myorg" --backend -``` - -You can scaffold plugins using CLI arguments to get started faster. This also allows you to run the tool in a non-interactive environment such as CI or to scaffold plugins with other tooling. - -Refer to the following table for the full list of prompt bypass options. - -| Prompt | Equivalent Argument Name | Values | -| ---------------- | ---------------------------- | -------------------------------------------------- | -| **Plugin type** | `--plugin-type` | one of `app`, `datasource`, `panel` or `scenesapp` | -| **Backend** | `--backend` / `--no-backend` | boolean | -| **Name** | `--plugin-name` | string | -| **Organization** | `--org-name` | string | diff --git a/docusaurus/docs/snippets/createplugin-update-force.npm.md b/docusaurus/docs/snippets/createplugin-update-force.npm.md new file mode 100644 index 000000000..f54a8f7e8 --- /dev/null +++ b/docusaurus/docs/snippets/createplugin-update-force.npm.md @@ -0,0 +1,3 @@ +```shell +npx @grafana/create-plugin@latest update --force +``` diff --git a/docusaurus/docs/snippets/createplugin-update-force.pnpm.md b/docusaurus/docs/snippets/createplugin-update-force.pnpm.md new file mode 100644 index 000000000..e30377527 --- /dev/null +++ b/docusaurus/docs/snippets/createplugin-update-force.pnpm.md @@ -0,0 +1,3 @@ +```shell +pnpm dlx @grafana/create-plugin@latest update --force +``` diff --git a/docusaurus/docs/snippets/createplugin-update-force.yarn.md b/docusaurus/docs/snippets/createplugin-update-force.yarn.md new file mode 100644 index 000000000..fc58ed509 --- /dev/null +++ b/docusaurus/docs/snippets/createplugin-update-force.yarn.md @@ -0,0 +1,3 @@ +```shell +yarn create @grafana/plugin update --force +``` diff --git a/docusaurus/website/docusaurus.config.base.js b/docusaurus/website/docusaurus.config.base.js index b74418d4b..612ac1d8f 100644 --- a/docusaurus/website/docusaurus.config.base.js +++ b/docusaurus/website/docusaurus.config.base.js @@ -193,6 +193,14 @@ const plugins = [ from: ['/create-a-plugin/extend-a-plugin/extend-configurations'], to: '/get-started/set-up-development-environment#extend-configurations', }, + { + from: ['/migration-guides/update-create-plugin-versions'], + to: '/reference/cli-commands/#update-plugin-tooling', + }, + { + from: ['/reference/prompts'], + to: '/reference/cli-commands/', + }, ], }, ],