docs: overhaul TypeDoc site and update markdown docs [DX-776]#2981
docs: overhaul TypeDoc site and update markdown docs [DX-776]#2981Lisa White (whitelisab) wants to merge 32 commits intomasterfrom
Conversation
Upgrades TypeDoc from 0.26 to 0.28.18 and adds typedoc-plugin-missing-exports and typedoc-github-theme. Rewrites typedoc.config.mjs from a 3-line stub into a full configuration covering entry points, navigation, categories, search boosts, and URL hosting. Adds @module + @category annotations to all create-*-api.ts legacy client files (create-contentful-api, create-space-api, create-environment-api, create-entry-api, create-organization-api, create-app-definition-api, create-environment-template-api) so they surface as distinct nav pages under "Legacy Client" — restoring the v4/v5 hierarchy of SpaceAPI → EnvironmentAPI → EntryAPI etc. Adds @module + @category Plain Client to plain-client.ts, plain-client-types.ts, and checks.ts, and @category Core to index.ts. Fixes: #1304 #1574 #1690 #1969 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Adds @module + @category Entities to all 83 lib/entities/*.ts files, re-enabling the Entities search boost in typedoc.config.mjs. Resolves all 52 TypeDoc warnings inherited from master (now 0): - Removed stale JSDoc-only tags: @memberof, @func, @description in environment-alias.ts, role.ts, and create-environment-api.ts - Fixed @example format: moved code fence to its own line after @example in space.ts, space-member.ts, space-membership.ts, create-environment-api.ts, and create-app-definition-api.ts - Fixed @params typo → @param in function.ts, function-log.ts, resource.ts - Corrected 16 @param name mismatches across create-contentful-api.ts, asset.ts, app-key.ts, upload-credential.ts, tag.ts, oauth-application.ts Improves JSDoc on high-traffic plain entity types (entry, asset, content-type): extracts inline type blocks from plain-client-types.ts into dedicated lib/plain/entities/ files with full @param/@returns/@throws/@example documentation on every method, including clarity on pagination variants (getMany vs getManyWithCursor) and full/partial update semantics (update vs patch). Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Add docs/getting-started.md: comprehensive intro covering both client styles (plain and legacy) with install, quickstart, pagination, asset upload, error handling, and TypeScript usage examples - Add docs/plugins/version-selector/: TypeDoc plugin that inlines a version dropdown on every generated page; fetches versions.json from the namespace base URL and navigates to the same relative path on change - Wire projectDocuments and version selector plugin into typedoc.config.mjs - Update release.yaml: set DOCS_BASE_URL before typedoc runs so hostedBaseUrl resolves to the versioned path, then generate versions.json on gh-pages after each deploy so the selector has data Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
…pages Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
…tion
Add typedoc-plain-api-hoist.mjs — a TypeDoc converter plugin that runs
before GroupPlugin (priority 100 vs -100) on EVENT_RESOLVE_END. For each
module in lib/plain/entities/, it moves the *PlainClientAPI type alias's
method children directly onto the module and removes the now-empty alias.
Before: sidebar entry "entry" → click → module page listing EntryPlainClientAPI
→ click again → methods (two clicks)
After: sidebar entry "entry" → click → methods directly on the module page
(one click, no internal type name exposed)
No TypeScript source changes; zero new warnings in the build.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
…iles Without these annotations the files were unnamed (TypeDoc used the full file path as the module name, producing titles like "Module plain/entities/entry") and uncategorised (appearing under "Other" rather than "Plain Client" in the sidebar). Each file now has: @module <basename> → title becomes "Module entry", "Module asset", etc. @category Plain Client → groups under Plain Client in the sidebar No conflict with lib/entities/*.ts (legacy entities) because those files use @module with no name, leaving them as path-based "entities/entry" etc. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Rename all 61 *PlainClientAPI types (e.g. EntryPlainClientAPI → EntryAPI) across lib/plain/entities/*.ts and lib/plain/plain-client-types.ts. With router: 'structure', TypeAliases get their own page. Each entity now has a dedicated page (e.g. /entry/EntryAPI) with all methods fully expanded inline — parameters, return types, throws, and examples — matching the v5 JSDoc structure where every entity is a single browsable page. Also removes the typedoc-plain-api-hoist.mjs plugin (no longer needed) and restores router: 'structure' (was left as 'member' from an experiment). No runtime behavior changes — these are type-only names in lib/plain/entities/ which are not part of the public lib/index.ts exports. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
…d types → Entities lib/entities/ files containing wrap* functions and chainable method types (publish, archive, update, etc.) are recategorised from @category Entities to @category Legacy Client. They belong there — they only exist to support the deprecated chainable client. 9 files that are purely shared data types with no legacy wrappers keep @category Entities: automation-definition, automation-execution, component-type, concept, concept-scheme, content-type-fields, field-type, utils, widget-parameters. Also adds category: Core frontmatter to getting-started.md so it appears under Core in the sidebar rather than Other. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
…t, shared types → Entities" This reverts commit 12b977bf840fe7ba4652aa1bdf2534f93ce364a9.
@category Entities was ambiguous — "entities" is a Contentful CMS term and doesn't clearly signal that this section contains shared TypeScript data shapes used by both clients. Updated across all 83 lib/entities/ files, typedoc.config.mjs (categoryOrder, searchCategoryBoosts), and getting-started.md. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Covers: - What @internal does and when to use it vs @Private - Module-level @module and @category conventions - How to document plain entity methods (summary, @param, @returns, @throws, @example fence placement) - Legacy entity deprecation pattern - What PR #2827 established (common-types @internal tagging, naming conventions, OptionalDefaults fix) Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
The legacy client is not fully deprecated — it's still supported and users need to be able to find its docs. Removing the module-level @deprecated tags prevents TypeDoc from rendering a deprecation banner on every Legacy Client page. Pre-existing method-level @deprecated tags (e.g. getAccessToken, getAccessTokens) and the @deprecated on ClientAPI itself are untouched — those are legitimately deprecated individual symbols. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
…y modules Add docs/shared-types.md — a guide page (category: Shared Types, appears first in that sidebar section) explaining that each module contains both shared *Props data shapes used by both clients and legacy wrapper classes (Entry, Asset, etc.) that are only used by the legacy chainable client. Includes a table mapping common symbols to which client uses them. Update module annotations on the 5 most-visited entity files (entry, asset, content-type, environment, space) to surface the same distinction inline on each module page, so users who land directly on e.g. /entities/entry/Entry understand what they're looking at without needing to find the guide first. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
…ntType, Space, Environment Each wrapper class/type previously had no JSDoc comment, so the type page opened with no description. Now each has a clear explanation that it is legacy client only, what it extends, and how plain client users get the equivalent data. Also corrects shared-types.md: legacy instance methods (entry.publish etc.) are documented in Shared Types alongside their wrapper class, not in the Legacy Client section. Legacy factory methods (environment.getEntry etc.) are in Legacy Client. The guide now accurately describes both. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
…vironment wrappers These comments appeared in IDE hover tooltips via .d.ts declaration files, which is not the intent. The shared-types.md guide page covers the plain vs legacy distinction for docs readers instead. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Adds `excludeExternals: true` to typedoc.config.mjs so that types from third-party packages (type-fest, Node built-ins, web streams) are no longer surfaced by typedoc-plugin-missing-exports. This eliminates the empty "Object", "Type Guard", and "Utilities" groups under create-organization-api. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Adds `category: Core` frontmatter to getting-started.md so it appears under Core in the sidebar instead of Other. Removes sidebarLinks for Getting Started, PlainClientAPI, and Legacy ClientAPI — they pointed to the hosted URL so they 404 locally, and all three pages are already reachable from the sidebar navigation. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Moves docs/getting-started.md into docs/Getting Started/ so TypeDoc renders it as a dedicated "Getting Started" group in the sidebar rather than grouping it under Core or Other. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Adds category: Getting Started frontmatter and lists it first in categoryOrder so it appears at the top of the sidebar as its own group, not lumped under Other. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Adds inline links to PlainClientAPI and checks pages in getting-started.md so users can navigate directly from the guide to the full method reference without hunting through the sidebar. Also boosts Getting Started and Core in searchCategoryBoosts so createClient surfaces higher in search results. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Adds lib/common-types.ts as an entry point so that shared type primitives (Link, SysLink, CollectionProp, MetaSysProps, patch types, etc.) get their own module page instead of being lumped into index. The index module now contains only createClient, RestAdapter, fetchAll, asIterator, and client-level config types. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Each create-*-api module page was empty because the exported API types are @internal. Adds a blockquote note to each module description pointing users to the corresponding entity in Shared Types where the methods are actually surfaced. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
The folder approach caused TypeDoc to render the child as "Getting Started/getting-started" in the sidebar. Moving the file back to docs/getting-started.md with category: Getting Started is enough — that category is already first in categoryOrder. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
![github-advanced-security[bot]](https://avatars.githubusercontent.com/in/57789?s=60&v=4){kind=small}
Wiz Scan Summary
To detect these findings earlier in the dev lifecycle, try using Wiz Code VS Code Extension. |
Changelist by BitoThis pull request implements the following key changes.
|
Impact Analysis by BitoInteraction DiagramsequenceDiagram
participant GitHub as GitHub Actions<br/>🔄 Updated | ●●○ Medium
participant TypeDoc as TypeDoc Plugin<br/>🟩 Added | ●●○ Medium
participant Selector as Version Selector<br/>🟩 Added | ●●○ Medium
participant Pages as GitHub Pages
GitHub->>TypeDoc: Load version-selector plugin
TypeDoc->>Selector: Inject CSS and JS into docs pages
GitHub->>Pages: Publish versioned documentation
GitHub->>Pages: Generate and commit versions.json
Note over Pages: Docs now support version navigation<br/>via dropdown selector
This MR adds a version selector to the SDK documentation and updates the release workflow to publish versioned docs with an auto-generated versions list. It introduces a TypeDoc plugin for injecting the selector, enhances the release process with docs publishing steps, and integrates with GitHub Pages for versioned hosting, improving developer experience for multi-version documentation access. Code Paths AnalyzedImpact: Flow: Direct Changes (Diff Files): Repository Impact: Cross-Repository Dependencies: Database/Caching Impact: API Contract Violations: Infrastructure Dependencies: Additional Insights: Testing RecommendationsFrontend Impact: Service Integration: Data Serialization: Privacy Compliance: Backward Compatibility: OAuth Functionality: Reliability Testing: Additional Insights: Analysis based on known dependency patterns and edges. Actual impact may vary. |
![bito-code-review[bot]](https://avatars.githubusercontent.com/in/1061978?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review Agent Run #8e052f
Actionable Suggestions - 7
-
lib/create-contentful-api.ts - 1
- Incomplete JSDoc · Line 94-94
-
lib/entities/asset.ts - 1
- API Naming Inconsistency · Line 120-120
-
lib/entities/role.ts - 1
- Incorrect JSDoc example · Line 70-77
-
lib/plain/entities/space-membership.ts - 1
- Invalid example parameter · Line 71-74
-
lib/plain/entities/entry.ts - 3
- Type Inconsistency in Entry Get Params · Line 115-119
- Documentation default mismatch · Line 344-344
- Misleading example variable · Line 349-349
Additional Suggestions - 1
-
lib/create-contentful-api.ts - 1
-
JSDoc Order · Line 401-401JSDoc standard requires param tags to precede github (@returns). The current order (github (@returns) before param) violates documentation conventions and may affect tooling.
-
Review Details
-
Files reviewed - 162 · Commit Range:
1b9bada..cba19ed- .github/workflows/release.yaml
- docs/plugins/version-selector/typedoc-version-selector.mjs
- docs/plugins/version-selector/version-selector.css
- docs/plugins/version-selector/version-selector.js
- lib/common-types.ts
- lib/create-app-definition-api.ts
- lib/create-contentful-api.ts
- lib/create-entry-api.ts
- lib/create-environment-api.ts
- lib/create-environment-template-api.ts
- lib/create-organization-api.ts
- lib/create-space-api.ts
- lib/entities/access-token.ts
- lib/entities/agent-run.ts
- lib/entities/agent.ts
- lib/entities/ai-action-invocation.ts
- lib/entities/ai-action.ts
- lib/entities/api-key.ts
- lib/entities/app-access-token.ts
- lib/entities/app-action-call.ts
- lib/entities/app-action.ts
- lib/entities/app-bundle.ts
- lib/entities/app-definition.ts
- lib/entities/app-details.ts
- lib/entities/app-event-subscription.ts
- lib/entities/app-installation.ts
- lib/entities/app-key.ts
- lib/entities/app-signed-request.ts
- lib/entities/app-signing-secret.ts
- lib/entities/app-upload.ts
- lib/entities/asset-key.ts
- lib/entities/asset.ts
- lib/entities/automation-definition.ts
- lib/entities/automation-execution.ts
- lib/entities/available-license.ts
- lib/entities/bulk-action.ts
- lib/entities/comment.ts
- lib/entities/component-type.ts
- lib/entities/concept-scheme.ts
- lib/entities/concept.ts
- lib/entities/content-semantics-index.ts
- lib/entities/content-type-fields.ts
- lib/entities/content-type.ts
- lib/entities/editor-interface.ts
- lib/entities/eligible-license.ts
- lib/entities/entry.ts
- lib/entities/environment-alias.ts
- lib/entities/environment-template-installation.ts
- lib/entities/environment-template.ts
- lib/entities/environment.ts
- lib/entities/extension.ts
- lib/entities/field-type.ts
- lib/entities/function-log.ts
- lib/entities/function.ts
- lib/entities/locale.ts
- lib/entities/oauth-application.ts
- lib/entities/organization-invitation.ts
- lib/entities/organization-membership.ts
- lib/entities/organization.ts
- lib/entities/personal-access-token.ts
- lib/entities/preview-api-key.ts
- lib/entities/release-action.ts
- lib/entities/release.ts
- lib/entities/resource-provider.ts
- lib/entities/resource-type.ts
- lib/entities/resource.ts
- lib/entities/role.ts
- lib/entities/scheduled-action.ts
- lib/entities/semantic-duplicates.ts
- lib/entities/semantic-recommendations.ts
- lib/entities/semantic-reference-suggestions.ts
- lib/entities/semantic-search.ts
- lib/entities/semantic-settings.ts
- lib/entities/snapshot.ts
- lib/entities/space-add-on.ts
- lib/entities/space-member.ts
- lib/entities/space-membership.ts
- lib/entities/space.ts
- lib/entities/tag.ts
- lib/entities/task.ts
- lib/entities/team-membership.ts
- lib/entities/team-space-membership.ts
- lib/entities/team.ts
- lib/entities/ui-config.ts
- lib/entities/upload-credential.ts
- lib/entities/upload.ts
- lib/entities/usage.ts
- lib/entities/user-ui-config.ts
- lib/entities/user.ts
- lib/entities/utils.ts
- lib/entities/webhook.ts
- lib/entities/widget-parameters.ts
- lib/entities/workflow-definition.ts
- lib/entities/workflow.ts
- lib/entities/workflows-changelog-entry.ts
- lib/index.ts
- lib/plain/checks.ts
- lib/plain/entities/agent-run.ts
- lib/plain/entities/agent.ts
- lib/plain/entities/ai-action-invocation.ts
- lib/plain/entities/ai-action.ts
- lib/plain/entities/app-access-token.ts
- lib/plain/entities/app-action-call.ts
- lib/plain/entities/app-action.ts
- lib/plain/entities/app-bundle.ts
- lib/plain/entities/app-definition.ts
- lib/plain/entities/app-details.ts
- lib/plain/entities/app-event-subscription.ts
- lib/plain/entities/app-installation.ts
- lib/plain/entities/app-key.ts
- lib/plain/entities/app-signed-request.ts
- lib/plain/entities/app-signing-secret.ts
- lib/plain/entities/app-upload.ts
- lib/plain/entities/asset.ts
- lib/plain/entities/automation-definition.ts
- lib/plain/entities/automation-execution.ts
- lib/plain/entities/comment.ts
- lib/plain/entities/component-type.ts
- lib/plain/entities/concept-scheme.ts
- lib/plain/entities/concept.ts
- lib/plain/entities/content-semantics-index.ts
- lib/plain/entities/content-type.ts
- lib/plain/entities/editor-interface.ts
- lib/plain/entities/entry.ts
- lib/plain/entities/environment-alias.ts
- lib/plain/entities/environment.ts
- lib/plain/entities/extension.ts
- lib/plain/entities/function-log.ts
- lib/plain/entities/function.ts
- lib/plain/entities/locale.ts
- lib/plain/entities/oauth-application.ts
- lib/plain/entities/organization.ts
- lib/plain/entities/resource-provider.ts
- lib/plain/entities/resource-type.ts
- lib/plain/entities/resource.ts
- lib/plain/entities/role.ts
- lib/plain/entities/semantic-duplicates.ts
- lib/plain/entities/semantic-recommendations.ts
- lib/plain/entities/semantic-reference-suggestions.ts
- lib/plain/entities/semantic-search.ts
- lib/plain/entities/semantic-settings.ts
- lib/plain/entities/space-member.ts
- lib/plain/entities/space-membership.ts
- lib/plain/entities/space.ts
- lib/plain/entities/tag.ts
- lib/plain/entities/task.ts
- lib/plain/entities/team-membership.ts
- lib/plain/entities/team-space-membership.ts
- lib/plain/entities/team.ts
- lib/plain/entities/ui-config.ts
- lib/plain/entities/upload-credential.ts
- lib/plain/entities/upload.ts
- lib/plain/entities/usage.ts
- lib/plain/entities/user-ui-config.ts
- lib/plain/entities/user.ts
- lib/plain/entities/webhook.ts
- lib/plain/entities/workflow-definition.ts
- lib/plain/entities/workflow.ts
- lib/plain/entities/workflows-changelog.ts
- lib/plain/plain-client-types.ts
- lib/plain/plain-client.ts
- typedoc.config.mjs
-
Files skipped - 5
- docs/getting-started.md - Reason: Filter setting
- docs/shared-types.md - Reason: Filter setting
- docs/typedoc-guide.md - Reason: Filter setting
- package-lock.json - Reason: Filter setting
- package.json - Reason: Filter setting
-
Tools
- Whispers (Secret Scanner) - ✔︎ Successful
- Detect-secrets (Secret Scanner) - ✔︎ Successful
- Eslint (Linter) - ✔︎ Successful
Bito Usage Guide
Commands
Type the following command in the pull request comment and save the comment.
-
/review- Manually triggers a full AI review. -
/pause- Pauses automatic reviews on this pull request. -
/resume- Resumes automatic reviews. -
/resolve- Marks all Bito-posted review comments as resolved. -
/abort- Cancels all in-progress reviews.
Refer to the documentation for additional commands.
Configuration
This repository uses Default Agent You can customize the agent settings here or contact your Bito workspace admin at jared.jolton@contentful.com.
Documentation & Help
AI Code Review powered by
| * @param params.organizationId - Organization ID | ||
| * @param params.environmentTemplateId - Environment template ID | ||
| * @param [params.version] - Template version number to return a specific version of the environment template | ||
| * @param params - organizationId, environmentTemplateId, and optional version number |
There was a problem hiding this comment.
The param params description for getEnvironmentTemplate is incomplete, missing the optional 'query' property that is part of the params object. This could lead to incomplete API documentation.
Code Review Run #8e052f
Should Bito avoid suggestions like this for future reviews? (Manage Rules)
- Yes, avoid them
Lisa White (whitelisab)
changed the title
3 participants
Summary
typedoc.config.mjsrewrite —router: 'structure',categorizeByGroup: false,excludeExternals: trueto prevent type-fest/Node built-in types from leaking into the sidebarcategoryOrderandsearchCategoryBoostsconfigured@moduleand@categoryannotations added to all 160+ source files so every entity gets its own dedicated page; type names retain their original*PlainClientAPInaming for backward compatibilitylib/common-types.tsadded as a dedicated Core entry point so shared primitives (Link,CollectionProp,MetaSysProps, etc.) have their own page rather than being buried in the index@exampleformatting fixed across alllib/files — backtick fences moved to their own line so TypeDoc renders them correctly as code blockslib/entities/andlib/plain/entities/(typo fixes, corrected example params and variable names, cleaned up redundant@params/@returnstags)docs/getting-started.md(plain client walkthrough with direct link toPlainClientAPI),docs/shared-types.md(explains theShared Typescategory),docs/typedoc-guide.md(contributor guide for adding TypeDoc annotations)create-environment-api,create-space-api) pointing users to the correct entity page in Shared Typesdocs/plugins/version-selector/) — fetchesversions.jsonfrom the deployed namespace, renders a<select>dropdown in the toolbar, preserves the current page path when switching versions; origin-validated before navigation to fix CodeQL DOM injection findingrelease.yamlupdated to build and deploy versioned docs togh-pagesafter each semantic release, withversions.jsongeneration andDOCS_BASE_URLinjection at build timepackage.json:build:docs→docs:build,docs:devnow uses TypeDoc's built-in--watch,docs:publishsimplified tonpm run docs:build,contentful-sdk-jsdocremoved (publishing is now fully handled by CI)Screenshot
Test plan
npm run docs:buildcompletes with 0 errors (3 known false-positive warnings about.htmlrelative paths in markdown are expected)/plain/entities/entry/EntryPlainClientAPIwith full method detail/create-environment-api) show the navigation callout pointing to the Shared Types entitycommon-typesappears as a dedicated Core module (not lumped into the index)type-festor Node built-in types (e.g.Except,SetOptional,Buffer) appear in the sidebar🤖 Generated with Claude Code