Docs: Set Up - AI sweep (#2263)

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Author: urbiz-grafana

docusaurus/docs/set-up/index.md

@@ -16,10 +16,20 @@ keywords:
   - configuration
 ---
 
-These guides walk you through setting up your development environment for Grafana plugin development. Including:
+# Set up your development environment
 
-- Running a development Grafana server with your plugin installed using Docker
-- Setting up GitHub workflows to automate your development and release process
-- Extending configurations for ESLint, Prettier, Jest, TypeScript, and Webpack
+This section helps you configure a complete development environment for Grafana plugin development. You'll learn how to set up local development tools and automate your development workflow.
+
+Before you begin, ensure you have the following:
+
+- A Grafana plugin project created with [`create-plugin`](/get-started.md)
+- Docker installed on your system
+- A GitHub repository for your plugin (optional, for CI/CD setup)
+
+These guides cover essential development environment setup:
+
+- **Docker environment**: Run a development Grafana server with your plugin installed using Docker.
+- **GitHub workflows**: Set up GitHub workflows to automate your development and release process.
+- **Configuration extensions**: Extend configurations for ESLint, Prettier, Jest, TypeScript, and Webpack.
 
 <DocLinkList />

docusaurus/docs/set-up/set-up-docker.md

@@ -29,21 +29,20 @@ It's not necessary to [sign a plugin](/publish-a-plugin/sign-a-plugin.md) during
 
 ## Why use the Docker environment
 
-We have chosen to use Docker because it simplifies the process of creating, deploying, and running applications. It allows you to create consistent and isolated environments for your plugin. This makes it easy to manage dependencies and ensure that the plugin runs the same way across different machines.
+Docker simplifies the process of creating, deploying, and running applications. It lets you create consistent and isolated environments for your plugin. This makes it easy to manage dependencies and ensures that your plugin runs the same way across different machines.
 
-With the `create-plugin` tool, the Docker container is configured with the necessary variables to allow easy access to Grafana and to load plugins without the need for them to be signed. The plugin tool also adds a live reload feature that allows you to make your frontend code changes to trigger refreshes in the browser, and changing the backend code will make the plugin binary to automatically reload.
+The `create-plugin` tool configures the Docker container with the necessary variables to allow easy access to Grafana and load plugins without signing them. The plugin tool also adds a live reload feature that triggers browser refreshes when you make frontend code changes, and automatically reloads the plugin binary when you change backend code.
 
-The docker environment also allows you to attach a debugger to the plugin backend code, making the development process easier.
+The Docker environment also lets you attach a debugger to the plugin backend code, making the development process easier.
 
 ## Get started with Docker
 
 To start your plugin development project, run the following commands in the order listed:
 
-1. <SyncCommand cmd="install" />: Installs frontend dependencies.
-1. <SyncCommand cmd="run dev" />: Builds and watches the plugin frontend code.
-1. `mage -v build:linux`: Builds the plugin backend code. Rerun this command every time that you edit your backend files.
-1. <SyncCommand cmd="run server" />: Starts a Grafana development server running on
-   [http://localhost:3000](http://localhost:3000).
+1. **Install dependencies**: <SyncCommand cmd="install" /> installs frontend dependencies.
+1. **Build frontend**: <SyncCommand cmd="run dev" /> builds and watches the plugin frontend code.
+1. **Build backend**: `mage -v build:linux` builds the plugin backend code. Rerun this command every time you edit your backend files.
+1. **Start server**: <SyncCommand cmd="run server" /> starts a Grafana development server running on [http://localhost:3000](http://localhost:3000).
 
 ## Configure the Grafana version
 
@@ -53,7 +52,7 @@ To test a plugin across different versions of Grafana, set an environment variab
 
 ## Configure the Grafana image
 
-The default Docker image in the plugin tool is `grafana-enterprise`. If you want to override this image, alter the `docker-compose.yaml` by changing the `grafana_image` build argument like so:
+The default Docker image in the plugin tool is `grafana-enterprise`. To override this image, alter the `docker-compose.yaml` by changing the `grafana_image` build argument:
 
 ```yaml title="docker-compose.yaml"
 version: '3.7'
@@ -73,11 +72,11 @@ This example assigns the environment variable `GRAFANA_IMAGE` to the build arg `
 
 ## Debugging a plugin's backend
 
-If you're developing a plugin with a backend part, run `npm run server` with `DEVELOPMENT=true`. The docker compose file exposes the port `2345` for debugging, from a headless delve instance that will run inside the docker environment.
-You can attach a debugger client to this port to debug your backend code.
-For example, in VSCode, you can add a `launch.json` configuration like this:
+If you're developing a plugin with a backend part, run `npm run server` with `DEVELOPMENT=true`. The Docker Compose file exposes port `2345` for debugging, from a headless delve instance that runs inside the Docker environment.
 
-```json
+You can attach a debugger client to this port to debug your backend code. For example, in VS Code, add a `launch.json` configuration:
+
+```json title="launch.json"
 {
   "version": "0.2.0",
   "configurations": [
@@ -94,7 +93,7 @@ For example, in VSCode, you can add a `launch.json` configuration like this:
       "substitutePath": [
         {
           "from": "${workspaceFolder}",
-          "to": "/root/<your-plugin-id>"
+          "to": "/root/<YOUR_PLUGIN_ID>"
         }
       ]
     }

docusaurus/docs/set-up/set-up-github.md

@@ -21,7 +21,7 @@ Automate your development process to minimize errors and make it faster and more
 
 ## The CI workflow
 
-The CI (`ci.yml`) workflow is designed to lint, type check, and build the frontend and backend. It is also used to run tests on your plugin every time you push changes to your repository. The `create-plugin` tool helps to catch any issues early in the development process, before they become bigger problems. For more information on end-to-end testing as part of the CI workflow, refer to our [documentation](/e2e-test-a-plugin/ci.md).
+The CI (`ci.yml`) workflow lints, type checks, and builds the frontend and backend. It also runs tests on your plugin every time you push changes to your repository. The `create-plugin` tool helps catch any issues early in the development process, before they become bigger problems. For more information on end-to-end testing as part of the CI workflow, refer to our [documentation](/e2e-test-a-plugin/ci.md).
 
 ## The release workflow
 
@@ -35,21 +35,19 @@ This workflow requires a Grafana Cloud API key. Before you begin, follow the ins
 
 ### Storing your Access Policy token as a repository secret in GitHub
 
-1. Access Repository Settings:
+1. **Access Repository Settings**:
+   - Go to your GitHub repository.
+   - Navigate to the **Settings** tab.
 
-- Go to your GitHub repository.
-- Navigate to the "Settings" tab.
+2. In the left sidebar, click on **Secrets and Variables** > **Actions**.
+3. Click on the **New repository secret** button.
+4. **Add Secret Information**:
+   - Enter the name for your secret: `GRAFANA_ACCESS_POLICY_TOKEN`.
+   - Paste the Access Policy Token value into the **Secret** field.
 
-2. In the left sidebar, click on Secrets and Variables -> Actions
-3. Click on the "New repository secret" button.
-4. Add Secret Information:
+5. Click on the **Add secret** button to save the secret.
 
-- Enter name for your secret - GRAFANA_ACCESS_POLICY_TOKEN.
-- Paste the Access Policy Token value into the "Secret" field.
-
-5. Click on the "Add secret" button to save the secret.
-
-Once the secret is stored, you can access it in your GitHub Actions workflow:
+After you store the secret, you can access it in your GitHub Actions workflow:
 
 ```yaml title="release.yml"
 name: Release
@@ -64,34 +62,34 @@ jobs:
           grafana_token: ${{ secrets.GRAFANA_ACCESS_POLICY_TOKEN }}
 ```
 
-In this example, the `secrets.GRAFANA_ACCESS_POLICY_TOKEN` variable is used to access the stored token securely within your GitHub Actions workflow. Make sure to adjust the workflow according to your specific needs and the language/environment you are working with.
+In this example, the `secrets.GRAFANA_ACCESS_POLICY_TOKEN` variable accesses the stored token securely within your GitHub Actions workflow. Adjust the workflow according to your specific needs and the language or environment you're working with.
 
 ### Triggering the workflow
 
 To trigger the release workflow, push a Git tag for the plugin version that you want to release:
 
-```bash
+```sh
 git tag v1.0.0
 git push origin v1.0.0
 ```
 
 ## The compatibility check workflow
 
-The compatibility check (`is-compatible.yml`) workflow is designed to check the Grafana API compatibility of your plugin every time you push changes to your repository. This helps to catch potential frontend runtime issues before they occur.
+The compatibility check (`is-compatible.yml`) workflow checks the Grafana API compatibility of your plugin every time you push changes to your repository. This helps catch potential frontend runtime issues before they occur.
 
 The workflow contains the following steps:
 
-1. Finding `@grafana` npm packages in your plugin.
-1. Extracting the exported types of the specified version.
-1. Comparing the differences between that version and the latest version.
-1. Looking for usages of those changed APIs inside your plugin.
-1. Reporting any potential incompatibilities.
+1. **Find packages**: Finds `@grafana` npm packages in your plugin.
+1. **Extract types**: Extracts the exported types of the specified version.
+1. **Compare versions**: Compares the differences between that version and the latest version.
+1. **Check usage**: Looks for usages of those changed APIs inside your plugin.
+1. **Report issues**: Reports any potential incompatibilities.
 
 ## The create plugin update workflow
 
-The create plugin update (`cp-update.yml`) workflow is designed to automate keeping your plugins development environment and dependencies up to date. It periodically checks the latest version of create-plugin listed on the npm registry and compares it to the version used by your plugin. If there is a newer version available the workflow will run the `create-plugin update` command, update the frontend dependency lockfile, then create a PR with the changes for review.
+The create plugin update (`cp-update.yml`) workflow automates keeping your plugin's development environment and dependencies up to date. It periodically checks the latest version of create-plugin listed on the npm registry and compares it to the version used by your plugin. If there's a newer version available, the workflow runs the `create-plugin update` command, updates the frontend dependency lockfile, then creates a PR with the changes for review.
 
-This workflow requires content and pull request write access to your plugins repo to be able to push changes and open PRs. Choose from the following two options:
+This workflow requires content and pull request write access to your plugin's repo to push changes and open PRs. Choose from the following two options:
 
 ### Use the default access token
 
@@ -118,7 +116,7 @@ jobs:
 
 ### Use a personal access token
 
-To use this option you must create a Github [fine-grained personal access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens) with access to the plugin repository and permission to read and write both `contents` and `pull requests`. Once created add the token to the plugin repository action secrets and then pass it to the action like so:
+To use this option, you must create a GitHub [fine-grained personal access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens) with access to the plugin repository and permission to read and write both `contents` and `pull requests`. After you create the token, add it to the plugin repository action secrets and then pass it to the action:
 
 ```yaml
 name: Create Plugin Update
@@ -139,7 +137,7 @@ jobs:
 
 ## The bundle stats workflow
 
-The bundle stats (`bundle-stats.yml`) workflow is intended to help developers keep an eye on the size of their plugins frontend assets. Changes in PRs trigger this workflow which will compare two webpack stats files; one from the default branch and the other from the PR. It then calculates differences between these assets sizes and posts a formatted comment to the PR giving an overview of any size differences.
+The bundle stats (`bundle-stats.yml`) workflow helps developers monitor the size of their plugin's frontend assets. Changes in PRs trigger this workflow, which compares two webpack stats files: one from the default branch and the other from the PR. It then calculates differences between these asset sizes and posts a formatted comment to the PR with an overview of any size differences.
 
 ```yaml title="bundle-stats.yml"
 name: Bundle Stats
@@ -173,4 +171,4 @@ jobs:
 
 #### Main stats artifact could not be found
 
-If you see this warning during bundle size workflow runs it means that the workflow failed to find the github artifact that contains the main branch stats file. The file can be generated by either merging a PR to main, pushing a commit to main, or manually running the workflow with workflow_dispatch.
+If you see this warning during bundle size workflow runs, it means that the workflow failed to find the GitHub artifact that contains the main branch stats file. You can generate the file by merging a PR to main, pushing a commit to main, or manually running the workflow with `workflow_dispatch`.