refactor(create-plugin): move panel-docs templates to templates/docs

Author: sunker

packages/create-plugin/src/codemods/additions/additions.ts

@@ -14,6 +14,6 @@ export default [
   {
     name: 'panel-docs',
     description: 'Scaffolds multi-page documentation for a Grafana panel plugin',
-    scriptPath: import.meta.resolve('./scripts/panel-docs/index.js'),
+    scriptPath: import.meta.resolve('./scripts/panel-docs.js'),
   },
 ] satisfies Codemod[];

…ditions/scripts/panel-docs/setup.test.ts …emods/additions/docs-scaffolding.test.tspackages/create-plugin/src/codemods/additions/scripts/panel-docs/setup.test.ts renamed to packages/create-plugin/src/codemods/additions/docs-scaffolding.test.ts packages/create-plugin/src/codemods/additions/scripts/panel-docs/setup.test.ts renamed to packages/create-plugin/src/codemods/additions/docs-scaffolding.test.ts

@@ -3,8 +3,8 @@ import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
-import { Context } from '../../../context.js';
-import { assertPluginType, setupDocsScaffolding } from './setup.js';
+import { Context } from '../context.js';
+import { assertPluginType, setupDocsScaffolding } from './docs-scaffolding.js';
 
 // capture the real existsSync before mocking so we can delegate to it in beforeEach
 const { existsSync: realExistsSync } = await vi.importActual<typeof import('node:fs')>('node:fs');
@@ -25,16 +25,14 @@ function makeContext(pluginJson: Record<string, unknown> = { type: 'panel', name
   return context;
 }
 
-describe('panel-docs/setup', () => {
+describe('docs-scaffolding', () => {
   const tempDirs: string[] = [];
 
-  // build a synthetic templateBaseUrl folder with the given docs template file contents
+  // build a synthetic plugin-type template folder with the given docs template file contents
   function makeTemplateBaseUrl(files: Record<string, string>): URL {
     const dir = mkdtempSync(join(tmpdir(), 'panel-docs-templates-'));
     tempDirs.push(dir);
     mkdirSync(join(dir, 'docs'), { recursive: true });
-    mkdirSync(join(dir, 'workflows'), { recursive: true });
-    writeFileSync(join(dir, 'workflows', 'validate-docs.yml'), 'name: Validate documentation\n');
     for (const [relPath, content] of Object.entries(files)) {
       const target = join(dir, 'docs', relPath);
       mkdirSync(join(target, '..'), { recursive: true });
@@ -43,6 +41,15 @@ describe('panel-docs/setup', () => {
     return pathToFileURL(`${dir}/`);
   }
 
+  // the templates every plugin type shares, mirroring templates/docs/common
+  function makeCommonTemplateBaseUrl(): URL {
+    const dir = mkdtempSync(join(tmpdir(), 'panel-docs-common-'));
+    tempDirs.push(dir);
+    mkdirSync(join(dir, 'workflows'), { recursive: true });
+    writeFileSync(join(dir, 'workflows', 'validate-docs.yml'), 'name: Validate documentation\n');
+    return pathToFileURL(`${dir}/`);
+  }
+
   beforeEach(() => {
     vi.mocked(existsSync).mockImplementation(realExistsSync);
   });
@@ -62,6 +69,7 @@ describe('panel-docs/setup', () => {
       context,
       docsPath: overrides.docsPath ?? 'docs',
       templateBaseUrl: makeTemplateBaseUrl(templates),
+      commonTemplateBaseUrl: makeCommonTemplateBaseUrl(),
       codemodName: 'panel-docs',
     });
   }
@@ -192,6 +200,7 @@ describe('panel-docs/setup', () => {
           context,
           docsPath: 'docs',
           templateBaseUrl: pathToFileURL(`${dir}/`),
+          commonTemplateBaseUrl: makeCommonTemplateBaseUrl(),
           codemodName: 'panel-docs',
         })
       ).toThrow(/Cannot find docs templates/);

…ds/additions/scripts/panel-docs/setup.ts …c/codemods/additions/docs-scaffolding.tspackages/create-plugin/src/codemods/additions/scripts/panel-docs/setup.ts renamed to packages/create-plugin/src/codemods/additions/docs-scaffolding.ts packages/create-plugin/src/codemods/additions/scripts/panel-docs/setup.ts renamed to packages/create-plugin/src/codemods/additions/docs-scaffolding.ts

@@ -1,9 +1,9 @@
 import { existsSync, readFileSync, readdirSync } from 'node:fs';
 import { join } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import type { Context } from '../../../context.js';
-import { output } from '../../../../utils/utils.console.js';
-import { additionsDebug, addDependenciesToPackageJson, isVersionGreater } from '../../../utils.js';
+import type { Context } from '../context.js';
+import { output } from '../../utils/utils.console.js';
+import { additionsDebug, addDependenciesToPackageJson, isVersionGreater } from '../utils.js';
 
 const REQUIRED_BUILD_PLUGIN_REF = 'build-plugin/v1.2.0';
 
@@ -17,12 +17,15 @@ export interface PluginJson {
 export interface DocsSetupOptions {
   context: Context;
   docsPath: string;
+  /** Templates specific to this plugin type, under `templates/docs/<type>/`. */
   templateBaseUrl: URL;
+  /** Templates shared by every plugin type, under `templates/docs/common/`. */
+  commonTemplateBaseUrl: URL;
   codemodName: string;
 }
 
 export function setupDocsScaffolding(opts: DocsSetupOptions): Context {
-  const { context, docsPath, templateBaseUrl, codemodName } = opts;
+  const { context, docsPath, templateBaseUrl, commonTemplateBaseUrl, codemodName } = opts;
 
   // step 1: early exit if the docs directory already exists on disk
   if (existsSync(join(context.basePath, docsPath))) {
@@ -56,7 +59,7 @@ export function setupDocsScaffolding(opts: DocsSetupOptions): Context {
   // step 6: copy validate-docs workflow, unless the user already customized one
   const workflowPath = '.github/workflows/validate-docs.yml';
   if (!context.doesFileExist(workflowPath)) {
-    const workflowContent = readTemplate(templateBaseUrl, 'workflows/validate-docs.yml').replaceAll(
+    const workflowContent = readTemplate(commonTemplateBaseUrl, 'workflows/validate-docs.yml').replaceAll(
       '{{docsPath}}',
       docsPath
     );

…ditions/scripts/panel-docs/index.test.ts …ods/additions/scripts/panel-docs.test.tspackages/create-plugin/src/codemods/additions/scripts/panel-docs/index.test.ts renamed to packages/create-plugin/src/codemods/additions/scripts/panel-docs.test.ts packages/create-plugin/src/codemods/additions/scripts/panel-docs/index.test.ts renamed to packages/create-plugin/src/codemods/additions/scripts/panel-docs.test.ts

@@ -1,7 +1,7 @@
 import * as v from 'valibot';
 import { describe, expect, it } from 'vitest';
-import { Context } from '../../../context.js';
-import panelDocs, { schema } from './index.js';
+import { Context } from '../../context.js';
+import panelDocs, { schema } from './panel-docs.js';
 
 function makeContext(): Context {
   const context = new Context('/virtual');

packages/create-plugin/src/codemods/additions/scripts/panel-docs.ts

@@ -0,0 +1,36 @@
+import * as v from 'valibot';
+import type { Context } from '../../context.js';
+import { assertPluginType, setupDocsScaffolding } from '../docs-scaffolding.js';
+
+export const schema = v.object({
+  docsPath: v.optional(
+    v.pipe(
+      v.string(),
+      v.minLength(1, 'docsPath must not be empty.'),
+      v.check(
+        (value) => !value.startsWith('/') && !value.split('/').includes('..'),
+        'docsPath must be a relative path without ".." segments.'
+      )
+    ),
+    'docs'
+  ),
+});
+
+type Options = v.InferOutput<typeof schema>;
+
+export default function panelDocs(context: Context, options: Options): Context {
+  assertPluginType(context, { expectedType: 'panel', codemodName: 'panel-docs' });
+  return setupDocsScaffolding({
+    context,
+    docsPath: options.docsPath,
+    // templates live in the package-root `templates/` folder alongside every other template set,
+    // split by plugin type so a future datasource-docs codemod reuses `docs/common/`. this file sits
+    // four levels below the package root in both `src/` and `dist/` - rollup mirrors the tree - so
+    // the same relative URL resolves from source and from the built package with no copy step.
+    // `templates/docs` is deliberately absent from TEMPLATE_PATHS, so `generate` ignores it until we
+    // scaffold docs for every new plugin.
+    templateBaseUrl: new URL('../../../../templates/docs/panel/', import.meta.url),
+    commonTemplateBaseUrl: new URL('../../../../templates/docs/common/', import.meta.url),
+    codemodName: 'panel-docs',
+  });
+}