[DEV-4124] Add docs structure metadata management

[Sebastiano-Bertolin]

This pull request introduces significant improvements to the documentation translation workflow and the supporting TypeScript scripts. The main focus is on enabling incremental updates and deletions to the docs-structure.json manifest, improving workflow flexibility, and refactoring code for maintainability and clarity.

Enhancements to the GitHub Actions workflow:

• Support for both uploading and deleting documentation paths is added, allowing more granular control over what is included or removed from the translation manifest.
• The workflow now commits and pushes changes to docs-structure.json only when the file has actually changed, reducing unnecessary commits. [1] [2]

Improvements to documentation and developer experience:

• The src/README.md is rewritten for clarity, providing a high-level workflow overview, detailed script documentation, manifest schema explanation, and clear instructions for workflow usage.

Major refactoring and new features in docsStructure.ts:

• Added support for incremental manifest updates and deletions via new helper functions and a mergeManifestWithSelectedPaths mechanism, making it possible to update or remove only selected nodes without rebuilding the entire manifest. [1] [2]
• Introduced utility functions for path normalization, label generation, manifest merging, and node deletion, improving code modularity and maintainability. [1] [2]
• The parsing of requested documentation paths is now centralized and shared between scripts, ensuring consistent input handling. [1] [2] [3] [4]

Script and interface updates:

• The generateDocStructure.ts script now reads both upload and delete path inputs, passes them to the manifest writer, and logs actions for better traceability.
• The WriteDocsStructureManifestOptions interface is introduced to support new options for manifest updates.

Summary of most important changes:

Workflow and automation improvements:

• Added support for paths_to_delete input in the GitHub Actions workflow, enabling removal of documentation nodes from the translation manifest. Workflow now commits docs-structure.json only if changed. (.github/workflows/upload_sources_to_crowdin.yml) [1] [2]

Documentation and developer experience:

• Rewrote src/README.md to provide a comprehensive overview of the workflow, scripts, manifest schema, and usage instructions.

Incremental manifest update and deletion:

• Refactored docsStructure.ts to support incremental updates and deletions in docs-structure.json, including new helpers for merging, node insertion, and deletion. [1] [2]
• Centralized and exported parseRequestedDocsPaths for consistent input parsing across scripts. [1] [2] [3] [4]

Script interface and logging:

• Updated generateDocStructure.ts to accept and process both upload and delete paths, and improved logging for user feedback.
• Added WriteDocsStructureManifestOptions interface for manifest writing flexibility.

[Copilot]

Pull request overview

This PR enhances the docs-to-Crowdin upload pipeline by enabling incremental updates and deletions in docs-structure.json, updating the GitHub Actions workflow to accept new inputs and avoid empty commits, and expanding documentation for maintainers.

Changes:

• Add incremental merge + deletion support to docs-structure.json generation and centralize requested-path parsing.
• Update the upload workflow to accept paths_to_delete, pass env vars consistently, and commit docs-structure.json only when changed.
• Rewrite/extend developer documentation explaining the workflow, scripts, and manifest.

Reviewed changes

Copilot reviewed 6 out of 7 changed files in this pull request and generated 9 comments.

Show a summary per file

File	Description
upload_sources_to_crowdin_workflow.md	New workflow deep-dive documentation for maintainers.
tsconfig.json	Broaden TS include globs to cover all scripts under src/.
src/README.md	Expanded documentation for scripts, manifest schema, and workflow inputs.
src/generateDocStructure.ts	Read upload/delete inputs and write manifest incrementally.
src/generateCrowdinConfig.ts	Reuse shared path parsing (removed local parser).
src/docsStructure.ts	Major refactor: merge/delete helpers, shared parsing, manifest write options.
.github/workflows/upload_sources_to_crowdin.yml	Add delete input, pass env vars, and conditionally commit manifest.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.