[OP-18657] Publish JS/TS API docs - #21688
Open
myabc wants to merge 13 commits into
Open
Conversation
myabc
added
documentation
maintenance
javascript
Contributor
There was a problem hiding this comment.
Pull request overview
This PR adds TypeDoc as a documentation generation tool for the frontend JavaScript/TypeScript code, replacing the previously unused Compodoc configuration.
Changes:
- Adds TypeDoc v0.28.16 as a dev dependency with appropriate configuration
- Removes the obsolete
tsconfig.compodoc.jsonconfiguration file - Configures documentation generation via
npm run generate-docs
Reviewed changes
Copilot reviewed 4 out of 5 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
| frontend/typedoc.json | New TypeDoc configuration targeting TypeScript files in app, stimulus, react, and turbo directories |
| frontend/tsconfig.compodoc.json | Removes unused Compodoc TypeScript configuration |
| frontend/package.json | Adds TypeDoc dependency and generate-docs npm script |
| frontend/package-lock.json | Locks TypeDoc and its transitive dependencies (lunr, mini-shiki, markdown-it, yaml) |
| frontend/.gitignore | Ignores generated documentation output directory |
Files not reviewed (1)
- frontend/package-lock.json: Language not supported
myabc
changed the title
myabc
force-pushed
the
code-maintenance/70566-tsjs-api-docs
branch
3 times, most recently
from
September 4, 2026 12:20
663f4fd to
ffd282a
Compare
TypeDoc renders the reference, its GitHub theme matches the surface the docs are linked from, and eslint-plugin-tsdoc keeps the doc comments parseable by the generator.
Scopes TypeDoc to the Stimulus entry points, excluding specs and the application bootstrap, so the reference describes reusable controllers, helpers and mixins rather than the whole frontend. Output is ignored rather than committed; `npm run generate-docs` builds it locally.
myabc
force-pushed
the
code-maintenance/70566-tsjs-api-docs
branch
from
September 4, 2026 21:10
a5bcc84 to
e5b7fd3
Compare
|
Warning Flaky specs
🤖 Ask Copilot to investigateCopy the prompt below into a new comment on this PR to delegate the investigation to GitHub Copilot. It will look into the flakiness and open a separate pull request with you as reviewer. |
Contributor
There was a problem hiding this comment.
🟡 Changes recommended
A newly added dependency chain introduces a TypeScript peer-range conflict (eslint-plugin-tsdoc → nested @typescript-eslint/* requiring TS <6.0.0 while the repo uses TS 6.0.3), which should be resolved or explicitly addressed to avoid toolchain breakage.
Once you've addressed the issues Copilot identified, you can request another Copilot review.
Review details
Files not reviewed (1)
- frontend/package-lock.json: Generated file
- Files reviewed: 23/24 changed files
- Comments generated: 1
- Review effort level: Lite
myabc
marked this pull request as ready for review
September 5, 2026 14:27
TypeDoc parses doc comments as TSDoc, not JSDoc, so a missing `@param`
hyphen, a `{Type}` after `@throws` or an unfenced code sample is dropped
or mangled in the generated output without warning.
Relocating the `@see` in CheckAllController also keeps the two
paragraphs that followed it out of the link.
Scoped to the `entryPoints` of `typedoc.json` rather than all of `src`, since the legacy Angular tree carries several hundred JSDoc comments that TypeDoc never renders.
Builds the reference for both the development tip and the latest release branch, so the published site can describe either. TypeDoc is installed ad-hoc rather than from the source checkout, letting release branches that predate this tooling still build. The generated output is validated before publishing, so a scope or naming regression fails the build rather than reaching the site.
test:tooling covered doc-generation tooling but no workflow called it, so a regression there would go undetected. Run it once per matrix job, on the chromium leg only.
Trigger paths omitted the tooling directory and tsdoc.json, so changes there would not rerun the build. Page-name assertions ran for the stage channel too, which tracks a release branch this workflow does not control. The out-of-scope module check passed vacuously when the modules directory was missing. And edge_ref/stage_ref could carry workflow_dispatch input into GITHUB_OUTPUT unescaped. Add the missing trigger paths, restrict exact page-name checks to edge, require the modules directory to exist, and switch edge_ref/stage_ref to the GITHUB_OUTPUT heredoc form.
The suite exercised the plugin through a fixture harness that omits `TypeDocReader`, so nothing asserted against the configuration actually shipped: dropping a plugin from `typedoc.json` left every test green. Adds a helper that converts real sources through that file, and two tests over it. Both were confirmed to fail under the mutation they guard — the plugin removed, and the source-link template corrupted. https://community.openproject.org/wp/OP-18657
myabc
force-pushed
the
code-maintenance/70566-tsjs-api-docs
branch
from
September 5, 2026 14:58
bb54167 to
f32d782
Compare
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
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.
Ticket
https://community.openproject.org/wp/OP-18657
What are you trying to accomplish?
Add a generated reference for Stimulus controllers, helpers, mixins and support modules so contributors and plugin authors can discover their source-level contracts. This complements Lookbook's component usage examples and establishes the infrastructure for a supported frontend API reference.
npm run generate-docs; output is git-ignored.node_modules.edgefrom the development tip andstagefrom the latest protected release branch. CI pins source links to the exact checkout commit and validates output before publication.npm run test:toolingand in CI.Screenshots
What approach did you choose and why?
TypeDoc initially covers
src/stimulus; including the legacy Angular tree would overwhelm the reference. TSDoc linting targets the same directory. Generated files stay out of the repository.CI installs pinned TypeDoc tooling and copies its configuration into each source checkout, allowing release branches that predate this tooling to build. Validation checks representative edge pages and rejects spec modules and APIs outside the intended scope. The inferred base path determines both page names and source-link paths; widening the entry points must update the link template alongside them.
PRs build and validate the site but skip GitHub Pages deployment. Outbound links from Lookbook and the frontend guide remain deferred until the site is published.
Follow-up work will define the supported API boundary, present controller identifiers and target/value/outlet attributes, and extend coverage to reusable code in
src/commonandsrc/turbo. These decisions are required before treating every generated symbol as a supported plugin API.Validation: all three tooling tests pass, full TypeDoc generation succeeds, and the current PR checks are green. Generation still emits 26 warnings, including unresolved references; syntax linting alone does not validate links.
Merge checklist