Skip to content

chore(docx): improve generateDocs script to run only for updated components with -t/--touched flag #2780

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.

Sign up for GitHub

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

Jump to bottom
Open
wants to merge 16 commits into
base: master
Choose a base branch
from
Open

chore(docx): improve generateDocs script to run only for updated components with -t/--touched flag #2780

wants to merge 16 commits into from
+167 −27

Conversation

nad182
Copy link
Contributor

@nad182 nad182 commented Oct 15, 2025

Motivations

  • Make the docs generator quieter and easier to operate, while keeping behavior consistent with the target branch.
  • Improve path stability in generated JSON and avoid unnecessary work when requested.

Changes

Added

  • -t/--touched mode: only write outputs when the source is newer than the existing JSON (mtime-based skip).
  • Unknown flag guard: fail fast on invalid flags with a short usage message.

Changed

  • Parse using a relative path so JSON filePath entries remain stable and relative.
  • Resolve base directories via __dirname/fileURLToPath and build paths via path.join.
  • DRY generation flow with a small generate() helper reused for web, native, and V2 auto-detect.
  • Reduce noisy per-item logs; print a concise end-of-run summary (parsed/updated/skipped) and list updated files.

Removed

  • Autocomplete V2 special-case (now covered by the generic V2 auto-detection).
  • Content-diff write logic (default runs always write; touched mode controls skipping via mtime).

Fixed

  • Stable filePath values in generated JSON by parsing via a relative path.

Security

  • n/a

Testing

  1. From packages/site, run npm run generate.
    • Expect all JSONs to be regenerated and a concise summary printed at the end.
  2. Run npm run generate -- -t.
    • Expect only stale outputs to be written; summary should show a non-zero Skipped count if nothing changed.
  3. Run npm run generate -- -g.
    • Expect an error about unknown flags with usage instructions.

nad182 added 5 commits October 8, 2025 14:32
@nad182
feat(site): improve docs generator with mtime skip, unchanged write a…
5e3f5c5 
…voidance, and summary output
@nad182
feat(site): generate V2 docs when *.rebuilt.tsx exists and write to <…
2798127 
…Component>V2
@nad182
feat(docx): enhance documentation generation by adding a filter to ex…
f848b5f 
…clude inherited React props

- Introduced a new function, `filterOutInheritedReactProps`, to clean up component documentation by removing inherited props from React base attributes.
- Updated the documentation processing pipeline in `generateDocs.mjs` to include this new filtering step.
- Removed unnecessary `key` prop entries from various component prop JSON files to streamline documentation.
@nad182
Resolve merge conflicts in generateDocs.mjs
d8a4f96 
- Combined import statements from both branches
- Merged function implementations with error handling and file change detection
- Integrated filterOutInheritedReactProps function for better prop filtering
- Combined V2 component generation approaches
- Added summary output for better user feedback
- Fixed all linting errors
@nad182
feat(docx): simplify docs generator, add touched mode and flag guard
eb756f8 
- Auto-detect <Component>.rebuilt.tsx and emit src/content/<Component>V2/<Component>V2.props.json
- Remove Autocomplete V2 one-off; rely on generic V2 detection
- Preserve relative file paths in output by parsing via relative path
@nad182 nad182 requested a review from a team as a code owner October 15, 2025 00:22
@nad182 nad182 marked this pull request as draft October 15, 2025 00:22
@cloudflare-workers-and-pages Cloudflare Workers and Pages
Copy link

cloudflare-workers-and-pages bot commented Oct 15, 2025 •
edited
Loading

Deploying atlantis with  Cloudflare Pages  Cloudflare Pages

Latest commit: 85646ff
Status: ✅  Deploy successful!
Preview URL: https://6612e8ae.atlantis.pages.dev
Branch Preview URL: https://cleanup-improve-generatedocs.atlantis.pages.dev

View logs

@nad182 nad182 changed the title build: improve generateDocs script (touched mode, flags, stable paths, summary) chore(docx): improve generateDocs script (touched mode, flags, stable paths, summary) Oct 15, 2025
@nad182 nad182 changed the title chore(docx): improve generateDocs script (touched mode, flags, stable paths, summary) chore(docx): improve generateDocs script to have a touched mode Oct 15, 2025
@nad182 nad182 changed the title chore(docx): improve generateDocs script to have a touched mode chore(docx): improve generateDocs script to run only for update components when running with -t flag Oct 15, 2025
nad182 added 10 commits October 16, 2025 13:54
@nad182
refactor: output V2 files in the same dir as V1
86308fe
@nad182
fix(docs): correct V2 props output path in documentation generation
47151c4 
- Updated the output path for V2 props to ensure they are written in the same directory as V1 props, improving organization and accessibility of generated documentation files.
- Adjusted the path construction in `generateDocs.mjs` to reflect this change.
@nad182
Generate V2 props in the same dir as V1
9edd355
@nad182
Use the new setup for combined Autocomplete (V1 and V2)
71547f1
@nad182
reverte Autocomplete index changes (will be done separately)
e4db841
@nad182
revert changes to Autocomplete index (will be done separately)
e5c652e
@nad182
remove remnants of Autocomplete v2 in v1 folder
7beaba0
@nad182
remove remnants of Autocomplete v2 in v1 folder
ac3f001
@nad182
remove remnants of Autocomplete v2 in v1 folder
faad17e
@nad182
Merge remote-tracking branch 'origin/JOB-138157/update-docgen-script-…
e25a3a9 
…for-V2-components' into CLEANUP/improve-generateDocs-script-to-run-only-for-updated-components
@nad182 nad182 mentioned this pull request Oct 20, 2025
Merged
@nad182 nad182 changed the title chore(docx): improve generateDocs script to run only for update components when running with -t flag chore(docx): improve generateDocs script to run only for updated components with -t/--touched flag Oct 20, 2025
Base automatically changed from JOB-138157/update-docgen-script-for-V2-components to master October 20, 2025 15:01
@nad182 nad182 marked this pull request as ready for review October 20, 2025 15:02
@nad182 nad182 requested a review from ZakaryH October 20, 2025 15:31
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@ZakaryH ZakaryH Awaiting requested review from ZakaryH

At least 1 approving review is required to merge this pull request.

Assignees

No one assigned

Labels

review requested Team UX Foundations

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@nad182