wip: add catalog docs codemod#2654
Draft
sunker wants to merge 12 commits into
Draft
Conversation
Contributor
|
Hello! 👋 This repository uses Auto for releasing packages using PR labels. ✨ This PR can be merged but will not trigger a new release. To trigger a new release add the |
sunker
added
minor
Adds the full `create-plugin add catalog-docs` command: - reads src/plugin.json to detect plugin type and set docsPath - adds @grafana/plugin-docs-cli devDependency and docs:serve/docs:validate scripts - copies type-specific markdown stubs into the docs folder with pluginName interpolation - copies validate-docs.yml CI workflow (always overwrites) - bumps build-plugin action ref in release.yml - idempotent: each step skips gracefully if already applied
- Move schema inline to index.ts, remove separate schema.ts - Remove h1 headings from all doc templates (frontmatter title is authoritative) - Fix workflow action versions to v4 (checkout, setup-node) - Update rollup.config.ts to glob nested codemod entry points and copy all templates dirs generically - Use runtime readFileSync approach for template loading (revert esbuild text loader approach) - Restore realExistsSync mock pattern in tests so template dir checks hit the real filesystem
sunker
force-pushed
the
eriksundell/catalog-docs-codemod-with-ai
branch
from
dce09de to
4438c6a
Compare
sunker
added
preview
@grafana/create-plugin
@grafana/eslint-plugin-plugins
@grafana/plugin-docs-cli
@grafana/plugin-docs-parser
@grafana/plugin-e2e
@grafana/plugin-meta-extractor
@grafana/plugin-types-bundler
@grafana/react-detect
@grafana/sign-plugin
@grafana/tsconfig
commit: |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This is a very rough draft, no need to study the code just yet. The PR will be split into multiple smaller ones before it's ready for review and merge.
What this PR does / why we need it:
Adds two
create-plugin addcodemods -panel-docsanddatasource-docs- that wires a plugin for multi-page documentation support.Beyond the wiring (adding devDep, npm scripts, tplugin.json setup and adds/changes workflows), each codemod also drops a set of plugin-type-specific stub Markdown files into
<docsPath>/. Every stub uses a section-brief protocol (<!-- section-brief:start --> ... <!-- section-brief:end -->) so a human or an agent has clear scope guidance for each H2.Optionally, opted into via
--agent-loop=claude|codex|cursor, the codemods also scaffold an AI authoring layer under<docsPath>/AGENTS.mdand the loop's skills folder:<docsPath>/AGENTS.md— the canonical authoring guide. Defines the frontmatter schema, filesystem conventions, agent-hint protocol, common page-pattern catalog, and a 13-rule style guide lifted (and adapted) from the Grafana Writers' Toolkit — voice, tense, person, headings, link text, em dashes etc. AGENTS.md is the file both humans and agents read first.write-plugin-docs(shared) — per-page authoring. Fills a stub or updates an existing page, reads the source files implied by the page title and section briefs, strips the briefs after.review-plugin-docs(shared) — plugin-specific review against the style guide, frontmatter schema, leftover section briefs and factual alignment with source.validate-plugin-docs(shared) — runsnpm run docs:validate --json, groups diagnostics, applies category-based fixes, loops up to 3 times.bootstrap-plugin-docs(per codemod, panel-specific or datasource-specific) — one-shot orchestrator. Inventoriessrc/,provisioning/dashboards/*.json, existing screenshots, README/CHANGELOG. Walks thePanelPlugin/DataSourcebuilder chains to extract option tables, standard field options, capability flags. Routes README content to stub pages, prompts the author for non-source-backed topics, then hands each page towrite-plugin-docs. Both bootstraps work on greenfield and brownfield plugins.Testing the canary build:
For a panel:
npx -y https://pkg.pr.new/@grafana/create-plugin@4438c6a add panel-docs --agentLoop claude|cursor|codex|none For a datasource:
npx -y https://pkg.pr.new/@grafana/create-plugin@4438c6a add datasource-docs --agentLoop claude|cursor|codex|none Which issue(s) this PR fixes:
Fixes #
Special notes for your reviewer: