Problem
scripts/generate_reference.py has grown into one big file. It defines the reference pages, reads manual reference pages, formats signatures, renders type links, checks parameter tables, and writes or checks the final files.
Because all of this is in one place, small docs-tooling changes are harder to review. For example, changing signature formatting means touching the same file that also has page content and file-writing logic.
Proposed behavior
Split this script into focused internal modules, but keep the existing commands working the same way.
The split should make these parts separate:
- page definitions;
- manual reference page loading;
- signature formatting;
- type and default rendering;
- table and reference validation;
- output writing and check mode.
npm run docs:reference and npm run docs:reference:check should still work the same.
This should be a refactor only. Please do not change the generated docs behavior in this issue.
Alternatives considered
We can keep everything in one file, but the file is already too large and mixes unrelated things. There is also a bigger idea to replace the docs tool, but this issue is smaller and only cleans up the current generator.
API sketch
No public API change is needed.
npm run docs:reference
npm run docs:reference:check
Working on this?
Please wait until a maintainer marks the issue accepted. After that, comment before starting and make sure nobody else is assigned or already working on it.
Problem
scripts/generate_reference.pyhas grown into one big file. It defines the reference pages, reads manual reference pages, formats signatures, renders type links, checks parameter tables, and writes or checks the final files.Because all of this is in one place, small docs-tooling changes are harder to review. For example, changing signature formatting means touching the same file that also has page content and file-writing logic.
Proposed behavior
Split this script into focused internal modules, but keep the existing commands working the same way.
The split should make these parts separate:
npm run docs:referenceandnpm run docs:reference:checkshould still work the same.This should be a refactor only. Please do not change the generated docs behavior in this issue.
Alternatives considered
We can keep everything in one file, but the file is already too large and mixes unrelated things. There is also a bigger idea to replace the docs tool, but this issue is smaller and only cleans up the current generator.
API sketch
No public API change is needed.
Working on this?
Please wait until a maintainer marks the issue
accepted. After that, comment before starting and make sure nobody else is assigned or already working on it.