-
Notifications
You must be signed in to change notification settings - Fork 41
feat(docs): refactor Building Block documentation — per-block docs/, committed catalog with CI sync gate #124
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Open
Simone319
wants to merge
10
commits into
main
Choose a base branch
from
zimzha/docs-restructure
base: main
Could not load branches
Branch not found: {{ refName }}
Loading
Could not load tags
Nothing to show
Loading
Are you sure you want to change the base?
Some commits from the old base branch may be removed from the timeline,
and old review comments may become outdated.
Open
Changes from all commits
Commits
Show all changes
10 commits
Select commit
Hold shift + click to select a range
5b49149
refactor(docs): per-block docs folders, merge index.md into docs/READ…
Simone319 52d8c9d
refactor(docs): commit BB catalog into README via markers + sync-docs…
Simone319 8aeefc7
docs: add Security Considerations to README, require.resolve locator …
Simone319 2bcd05e
docs: note AWS credentials + least-privilege for sandbox/deploy
Simone319 a1e92ab
refactor(docs): split catalog (sync-catalog) from docs-artifact (gen-…
Simone319 cc82f2d
docs: drop per-block links from catalog/prose; locate docs via resolv…
Simone319 96248e5
ci: scope workflow GITHUB_TOKEN to contents:read; deterministic (code…
Simone319 31ec72e
Merge remote-tracking branch 'origin/main' into zimzha/docs-restructure
Simone319 2705011
Merge branch 'main' into zimzha/docs-restructure
Simone319 ef73022
Merge branch 'main' into zimzha/docs-restructure
Simone319 File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,16 @@ | ||
| --- | ||
| "@aws-blocks/blocks": patch | ||
| "@aws-blocks/create-blocks-app": patch | ||
| --- | ||
|
|
||
| docs: per-block docs folders + committed BB catalog with CI sync check; CLAUDE/agents docs resolved via require.resolve | ||
|
|
||
| `@aws-blocks/blocks` now ships one docs folder per Building Block under `docs/<block>/` | ||
| (`README.md` / `API.md` / `DESIGN.md`), plus a committed, marker-delimited Building Block | ||
| catalog in the package README that a `sync-docs --check` CI gate keeps in sync. The README's | ||
| catalog section and the scaffolded `AGENTS.md` (`@aws-blocks/create-blocks-app`) now direct | ||
| tools and agents to locate docs programmatically via | ||
| `require.resolve('@aws-blocks/blocks/docs/<block>/README.md')` (and | ||
| `require.resolve('@aws-blocks/blocks/docs/README.md')` for the catalog) rather than assuming a | ||
| `node_modules/` path or following the human-facing relative links. Also adds a Security | ||
| Considerations section to the package README. |
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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,25 @@ | ||
| name: Block Catalog Check | ||
|
|
||
| # Fails the PR if the generated Building Block catalog table in | ||
| # packages/blocks/README.md is out of date. The script only reads the committed | ||
| # package READMEs + root README (Node builtins, zero deps), so no `npm ci` needed. | ||
| # On failure its stderr tells the engineer to run `npm run sync-docs` and commit. | ||
|
|
||
| on: | ||
| pull_request: | ||
| branches: [main] | ||
|
|
||
| permissions: | ||
| contents: read | ||
|
|
||
| jobs: | ||
| check: | ||
| name: Catalog in sync | ||
| runs-on: ubuntu-latest | ||
| steps: | ||
| - uses: actions/checkout@v5 | ||
| - uses: actions/setup-node@v5 | ||
| with: | ||
| node-version-file: '.nvmrc' | ||
| - name: Verify Building Block catalog is in sync | ||
| run: node scripts/sync-catalog.mjs --check | ||
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
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
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
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
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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,79 @@ | ||
| #!/usr/bin/env node | ||
| // Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved. | ||
| // SPDX-License-Identifier: Apache-2.0 | ||
|
|
||
| /** | ||
| * Generates the gitignored, shipped `docs/` artifact for @aws-blocks/blocks. Runs | ||
| * as the packages/blocks `prebuild` hook so the published package always carries | ||
| * fresh docs without dirtying any tracked file. | ||
| * | ||
| * It produces two things under packages/blocks/docs/: | ||
| * 1. Per-block folders docs/<pkg>/ — mirror every root-level *.md of each | ||
| * included package EXCEPT the ones in SKIP_MARKDOWN (CHANGELOG.md), so | ||
| * block-specific docs (README.md, API.md, DESIGN.md, ...) ship automatically. | ||
| * 2. docs/README.md — a verbatim copy of the committed packages/blocks/README.md. | ||
| * | ||
| * This script NEVER modifies packages/blocks/README.md. The committed catalog | ||
| * table inside that README is managed separately by scripts/sync-catalog.mjs | ||
| * (`npm run sync-docs`); run that and commit before building if you added or | ||
| * removed a block. | ||
| * | ||
| * No flag is required — the default run generates docs/. `--docs-only` is accepted | ||
| * as a harmless alias for the same behavior. | ||
| * | ||
| * Inclusion rule: every package under packages/ that has a README.md and is not in | ||
| * EXCLUDED. (The package-discovery logic is intentionally duplicated from | ||
| * sync-catalog.mjs — the two scripts are kept independent on purpose.) | ||
| */ | ||
|
|
||
| import { readFileSync, writeFileSync, mkdirSync, readdirSync, existsSync, rmSync } from 'node:fs'; | ||
| import { join, dirname } from 'node:path'; | ||
| import { fileURLToPath } from 'node:url'; | ||
|
|
||
| const __dirname = dirname(fileURLToPath(import.meta.url)); | ||
| const packagesDir = join(__dirname, '..', 'packages'); | ||
| const outDir = join(packagesDir, 'blocks', 'docs'); | ||
| const readmePath = join(packagesDir, 'blocks', 'README.md'); | ||
|
|
||
| const EXCLUDED = new Set(['blocks', 'data-common', 'foundations', 'create-blocks-app']); | ||
|
|
||
| // Root-level markdown that should NOT be mirrored into the per-block doc folder. | ||
| const SKIP_MARKDOWN = new Set(['CHANGELOG.md']); | ||
|
|
||
| const packages = getPackages(); | ||
|
|
||
| generatePerBlockDocs(); | ||
| writeFileSync(join(outDir, 'README.md'), readFileSync(readmePath, 'utf-8')); | ||
|
|
||
| console.log(`Generated ${packages.length} block docs → packages/blocks/docs/`); | ||
|
|
||
| // ─── docs/ artifact ────────────────────────────────────────────────────────── | ||
|
|
||
| function generatePerBlockDocs() { | ||
| // Clean and recreate so removed blocks/files don't linger. | ||
| rmSync(outDir, { recursive: true, force: true }); | ||
| mkdirSync(outDir, { recursive: true }); | ||
|
|
||
| for (const pkg of packages) { | ||
| const pkgDir = join(packagesDir, pkg); | ||
| const blockOutDir = join(outDir, pkg); | ||
| mkdirSync(blockOutDir, { recursive: true }); | ||
|
|
||
| // Mirror every root-level markdown file (README.md, API.md, DESIGN.md, and any | ||
| // block-specific docs) except the skipped ones, so new docs ship automatically. | ||
| const mdFiles = readdirSync(pkgDir, { withFileTypes: true }).filter( | ||
| (entry) => entry.isFile() && entry.name.endsWith('.md') && !SKIP_MARKDOWN.has(entry.name), | ||
| ); | ||
| for (const entry of mdFiles) { | ||
| writeFileSync(join(blockOutDir, entry.name), readFileSync(join(pkgDir, entry.name), 'utf-8')); | ||
| } | ||
| } | ||
| } | ||
|
|
||
| // ─── Package discovery (duplicated from sync-catalog.mjs) ────────────────────── | ||
|
|
||
| function getPackages() { | ||
| return readdirSync(packagesDir).filter( | ||
| (name) => !name.startsWith('.') && !EXCLUDED.has(name) && existsSync(join(packagesDir, name, 'README.md')), | ||
| ); | ||
| } |
Oops, something went wrong.
Oops, something went wrong.
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.
Uh oh!
There was an error while loading. Please reload this page.