docs: generate component and page type documentation from forms-model types#380
Open
alexluckett wants to merge 41 commits intomainfrom
Open
docs: generate component and page type documentation from forms-model types#380alexluckett wants to merge 41 commits intomainfrom
alexluckett wants to merge 41 commits intomainfrom
Conversation
alexluckett
force-pushed
the
docs/components
branch
from
40e0533 to
556b53f
Compare
alexluckett
changed the title
alexluckett
changed the title
…aces, YAML quoting
…ased and code-based
The @adobe/jsonschema2md tool slugifies JSON schema titles into filenames. The @defra/forms-model v2 schema has deeply nested titles that compound on each other (e.g. "Components (array)" → "Components (array) Item" → "Components (array) Item (object)"), producing filenames of ~252 chars. As .md files they fit within the 255-byte OS limit, but Docusaurus writing them as .html pushes them to 257+ bytes, causing ENAMETOOLONG on Linux CI. Add simplifyNestedTitles() which strips the parent title prefix from child titles before jsonschema2md runs (e.g. "Components (array) Item" → "Item"). The original title is passed down the hierarchy so multi-level stripping works correctly. Whitespace is normalised when matching to handle the double-space present in some schema titles.
…etadata is descriptions only
…us link validation errors
…ill required fields
Page metadata is now `controllerKey: description` strings only, matching the shape of component metadata. Labels, controller values, sidebar positions, unique properties, and JSON examples are all derived from the TypeScript interfaces in @defra/forms-model at generation time.
- Add fs.existsSync guards for enumsDtsPath and formDefinitionDtsPath - Warn when a page key in metadata.pages has no matching interface data - Export pure functions and guard main() for testability - Add 45 unit tests covering all exported pure functions - Fix predocs:dev to run both generators (schema + component)
…component notes - Remove BASE_OPTION_PROPS and BASE_PAGE_PROPS filters so all props appear in each component/page table, sorted alphabetically; props typed as undefined (e.g. section on PageSummary) are automatically excluded - Derive CONTROLLER_INTERFACE_MAP from ControllerType enum instead of hardcoding - Derive CONTROLLER_PATH_HINTS from ControllerPath enum instead of hardcoding - Remove PAGES_WITHOUT_NEXT; derive from uniqueProps at example generation time - Remove GEOSPATIAL_NAMES and payment category; geospatial/payment components now appear under Input fields - Add componentLinks metadata for HiddenField (pre-populate state) and all five geospatial components (map/API key requirement) - Document ordnanceSurveyApiKey/Secret in plugin-options.md with a Geospatial map section - Add pageProperties descriptions for all universal page props
…eferences - Fix features/index.md heading links — relative paths from an index page require the parent directory name to resolve correctly against the base URL - Add componentLinks note on FileUploadField pointing to FileUploadPageController - Add pageLinks support to generatePageMd for page-level supplementary notes - Add pageLinks note on FileUploadPageController pointing to file-upload.md guide
…ops collection - Collect all non-universal top-level component properties (anything not in type/name/title/id/options/schema) from the full inheritance chain - Render them in a new ## Properties table above ## Options - Remove hasList and hasContent flags — now redundant - Surface hint and shortDescription (inherited from FormFieldBase) with descriptions - Add list and hint descriptions to component-metadata.json
…ningful placeholders
…t prop - Hoist UNIVERSAL set to module level (was recreated on every interface iteration) - Extract parseSourceFile helper to deduplicate read+parse+allInterfaces setup - Exclude `next` from page props — v2 engine derives routing from pages[] order and condition
…urn, use replaceAll
…hemaChildren complexity
alexluckett
force-pushed
the
docs/components
branch
from
ca7c300 to
c78f2f4
Compare
H3 subheadings under Steps 1, 6 and Foundational knowledge caused the theme to render those H2s as non-interactive spans rather than anchor links. Adding <!-- no-sidebar --> excludes them from sidebar generation so every top-level step appears as a link.
- Rewrite Foundational knowledge section for conciseness - Promote "Optional dependencies" to a proper heading - Align CDP wording in Step 4 (both items now say "If you are on CDP") - Remove redundant "as files" in Step 6 intro - Fix trailing "and" on conditions bullet, expand pages bullet description
- Add missing node:path, @hapi/vision and nunjucks imports to Step 3 - Add @hapi/vision registration block (was listed as a dependency but never shown being registered in the full example) - Fix viewContext return object: missing comma and string key syntax - Add SESSION_COOKIE_PASSWORD as a required env var in Step 5
|
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.
Proposed change
Adds a build-time documentation generator that reads
@defra/forms-modelTypeScript declaration files and produces Markdown pages for every component type and page controller, keeping docs automatically in sync with model changes.The generator walks the TypeScript AST to resolve full inheritance chains, intersection types, and indexed access types (e.g.
DateFieldBase['options'] & { condition?: string }). Human-readable descriptions and cross-links are maintained incomponent-metadata.json.Each component page includes a JSON example, properties table, options table, and schema constraints table. Each page controller page includes a JSON example and configuration table, with index pages for both sections. Also rewrites the plugin options docs as a table and adds custom controllers and custom filters sections.
This also fixes the documentation build-time issue when extra-long page names were encountered.
Jira ticket:
Technical summary
scripts/generate-component-docs.jsruns pre-build and outputs intodocs/features/components/anddocs/features/pages/(both gitignored). It uses the TypeScript compiler API — rather than string parsing — to read@defra/forms-model's.d.tsfiles, so inheritance chains and complex type expressions resolve correctly. Descriptions and cross-links are kept separately inscripts/component-metadata.jsonso the generator stays logic-only.Type of change
Checklist
README.mdanddocs/*(where appropriate, e.g. new features).npm run test).npm run lint).npm run format).