docs: components/<Name>/README.md is the catalog source#261
Merged
Conversation
Consolidates the catalog's per-component markdown into each component's
README.md and retires bin/_docs_components/ entirely.
Before:
components/<Name>/README.md — Composer/Packagist surface
bin/_docs_components/<slug>.md — docs-site catalog
bin/_extract_catalog.py — one-shot migration tool
After:
components/<Name>/README.md — both Composer/Packagist surface AND
docs-site catalog. Frontmatter at the
top (slug/title/install/credit_*/
see_also) drives the docs site;
GitHub's renderer hides it from the
README view on github.com.
Why: the two files had overlapping content (lede, intro prose) and
nothing structural prevented drift. Co-locating the catalog with the
component eliminates the duplication, removes the bin/_docs_components/
indirection, and keeps everything one Composer package needs in one
file.
Pipeline change is small:
- bin/_load_catalog.py: COMPONENT_DIR replaced by COMPONENT_ORDER
(slug → directory tuples, kept ordered) reading from
components/<Name>/README.md.
- bin/run-snippets.py: --update writes captured stdout back into the
same README via the same slug → directory map.
- bin/build-reference.py: docstring only.
- .github/workflows/{docs,snippet-tests}.yml: dropped
`bin/_docs_components/**` from path filters.
- bin/_docs_components/ and bin/_extract_catalog.py deleted.
- bin/_docs_components.py keeps its small structural metadata
(STARTER_PATHS, COMPONENT_GUIDES) plus `COMPONENTS = load_components()`.
Verified: bin/run-snippets.py --check → 87/87 still pass; build-reference.py
regenerates docs/reference/ cleanly.
Note: replacing the old per-package READMEs with the catalog content drops
some "API Reference" tables that lived only in the old READMEs (Polyfill's
function list, ByteStream's interfaces, Merge's strategies, HttpServer's
class list, etc.). Most of those were redundant with the new "When to use
which" tables already in the catalog; if any are worth keeping, they can
be added back as new sections in the README in a follow-up — they'll then
appear on the docs site too.
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
1 participant
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.
Summary
Consolidates the catalog's per-component markdown into each component's
README.mdand retiresbin/_docs_components/entirely.components/<Name>/README.md(Composer/Packagist surface)components/<Name>/README.md— both Composer/Packagist surface and docs-site catalog.bin/_docs_components/<slug>.md(docs-site catalog)bin/_extract_catalog.py(one-shot migration tool)YAML-style frontmatter at the top of each README (
slug,title,install,credit_title+credit_body, repeatedsee_also: …) drives the docs site. GitHub's README renderer hides frontmatter from the github.com view, so it's invisible to a reader landing on a component's directory page or on Packagist — but the build pipeline parses it.Why
The two files had overlapping content (lede, intro prose) and nothing structural prevented drift. Co-locating the catalog with its component eliminates duplication, removes the
bin/_docs_components/indirection, and keeps everything one Composer package needs in one file. No generation step.Pipeline change is small
bin/_load_catalog.py:COMPONENT_DIR→COMPONENT_ORDER(slug → directory tuples, ordered) reading fromcomponents/<Name>/README.md.bin/run-snippets.py:--updatewrites captured stdout back into the same README via the same slug → directory map.bin/build-reference.py: docstring only..github/workflows/{docs,snippet-tests}.yml: droppedbin/_docs_components/**from path filters.bin/_docs_components/directory andbin/_extract_catalog.pydeleted.bin/_docs_components.pykeeps its small structural metadata (STARTER_PATHS,COMPONENT_GUIDES) plusCOMPONENTS = load_components().Test plan
Verify docs snippetsworkflow passes (87/87).Deploy docs to GitHub Pagesruns cleanly on push to trunk; live reference pages render with snippets.Note: lost API tables
Replacing the old per-component READMEs with the catalog content drops some API Reference tables that lived only in the old READMEs (Polyfill's function list, ByteStream's interfaces, Merge's strategies, HttpServer's class list, etc.). Most were redundant with the new "When to use which" comparison tables already in the catalog. If any are worth keeping, they can be added back as new sections in the README in a follow-up — they'll then appear on the docs site too, since the README is the docs source.
🤖 Generated with Claude Code