v0.24 Beta Release

[Gerrit0]

TypeDoc 0.24 is the next major release of TypeDoc. Please try it out and report any issues either as comments in this issue or as new issues.

npm install --save-dev typedoc@beta

This release includes two major features, support for reviving a project from previously serialized json, and a complete rework of the packages mode. See the changelog for notes on API breaking changes.

JSON Deserialization

TypeDoc has been able to output JSON files describing the converted project in previous releases, but these JSON files were originally intended only for use by external programs to generate custom documentation sites. With this release, TypeDoc can read JSON files produced in a previous run and create a rendered HTML site from them.

To support this feature, the serialized form of a project was updated to include more information about unresolved symbols, which makes it possible for cross-project type links to be resolved even after serialization if TypeScript's declarationMap option was enabled when compiling the dependency.

While useful, the largest benefit from this feature comes from the way JSON files are consumed. There is a new --entryPointStrategy value, merge, which accepts one or more JSON files and creates a single project with the content of all files. This feature means that it is now possible to generate documentation for completely unrelated packages and merge it together into a single site.

# docs for project 1
npx typedoc src/index.ts --json project1.json
# docs for project 2
npx typedoc src/index.ts --json project2.json
# create merged site
npx typedoc --entryPointStrategy merge path/to/project1.json path/to/project2.json

Reworked packages mode

TypeDoc's packages mode, introduced in v0.22.0, was intended to improve documentation generation for monorepos by treating each package individually while still producing a single site. It achieved this goal in some cases, but the implementation required keeping an instance of the TS compiler in memory for all packages in order to generate documentation. This led to major memory issues (#1606), and since symbol resolution still relied on ts.Symbol identity, meant that TypeDoc was still unable to create links to types declared in a different package, even if it was included in the documentation. It also frequently required custom configuration in the package.json files of packages with option names that were different than TypeDoc's normal options.

v0.24 completely overhauls how packages mode works. Packages mode now uses the JSON deserialization feature to convert each project and then convert it to JSON. Once all projects have been converted, it merges the simple objects into a single project and renders that project. With this method, only one ts.Program is kept in memory at a time. This method also benefits from the work to enable cross-project type links in JSON deserialization, and since TypeDoc runs in each project, TypeDoc can be configured with the standard options available when running on a single project.

Important Breaking Changes

• Dropped support for legacy [[link]]s and link resolution.
• TypeDoc no longer automatically loads plugins from node_modules, specify the plugins you want to load with the --plugin option.
• Reworked packages mode, the old packages mode will be available as legacy-packages until v0.25.

Remaining Work

Will be included in this release:

• Merge Introduce an options reader for package.json files #2129
• Update readme to reflect packages mode changes
• Review/update documentation in https://github.com/TypeStrong/typedoc/tree/beta/internal-docs
• Update website documentation
• Figure out what to do about the empty modules package when using packages mode

May be included in this release:

• Review Cascade namespace tags to individual API members in rendered doc #2056
• Review Methods marked with @internal show up in the docs for child classes if redeclared #2084
• Investigate introducing an option for resolving links using the compiler by default, and falling back to declaration references on failure to be closer to VSCode's behavior, @link is Disconnected from VSCode - Makes @link near-impossible to use effectively #2141

[Gerrit0]

v0.24.0-beta.3

• Updated internal-docs folder
• Added a warning if config for legacy-packages is discovered in packages mode
• Changed default value of out option, Default value for out option #2195
• Moved navigation to left of content, Move sidebar to the left of content #2192
• Introduced an options reader for package.json files, Introduce an options reader for package.json files #2129
• Created packages example setup - https://github.com/Gerrit0/typedoc-packages-example

[matteobruni]

Hi @Gerrit0, I've tested the 0.24.0-beta.3 but I think there's an improvement to do:

The modules are not collapsible in the sidebar, only the Modules menu, which can be hard to navigate if you have a long export list or many modules.

I've installed the beta version in the v2 branch, if you need to check that.

[Gerrit0]

I'm probably not going to get to adjusting that behavior for this release, it's the same as the previous versions, and frontend isn't really what I enjoy doing - PR welcome if you have a better way!

[Gerrit0]

v0.24.0-beta.4 (based on 0.23.28)

• Introduced a new option, useTsLinkResolution which defaults to true. When set, TypeDoc will use TypeScript's resolution of @link/@linkcode/@linkplain links if possible before falling back to declaration reference resolution.
• Fixed @inheritDoc on signatures being unable to inherit from reflections not containing signatures
• Added @overload to default ignored tags
• Support TS 5.0

[Gerrit0]

v0.24.0-beta.5/6 (based on 0.23.28)

• Added support for @interface to tell TypeDoc to resolve a type alias' type to its known properties/signatures, Utility functions are included in output, instead of their resolved final types #1519.
• Added support for @prop or @property to define comments for children of a reflection, intended for use with @interface.
• Added support for @namespace on variable declarations to tell TypeDoc to convert the variable as a namespace, Support for @namespace marking a variable as a namespace #2055.
• Added --cacheBust option to include the generation timestamp in links to assets, Is cache busting supported? #2124.
• Interfaces/classes created via extending a module will no longer contain variables/functions where the member should have been converted as properties/methods, Mark functions that are children of classes or interfaces as methods #2150.

I think this may be the last beta release of 0.24, useTsLinkResolution was the last big feature I wanted to get in, #2056 and #2084 will likely end up waiting for 0.25.

[Gerrit0]

.. okay, this should be the last one.

v0.24.0-beta.7

• Fixed an issue when useTsLinkResolution is on and scoped links ({@link Foo.bar | text}) were used (would be rendered as .bar | text instead of text)

[RunDevelopment]

includeVersion: true doesn't work. Here's the diff between 0.23.28 and 0.24.0-beta.7:

[Gerrit0]

It seems to work properly for me - could you share a reproduction, or at least what entry point strategy you're using?

[RunDevelopment]

Sure. I found this issue in this repo. Install 0.24.0-beta.7 there, and you should be able to reproduce it. typedoc.json for reference.

[Gerrit0]

Ah, I forgot to update a couple places in the UI to display versions, thanks!

Turns out that there's an extra feature coming in 0.24, #2218 led to my getting nerd sniped by the navigation.. Assuming nothing badly broken turns up, 0.24 should fully release next weekend.

v0.24.0-beta.8

• Completely reworked navigation rendering to better support browsing, Smarter sidebar default scroll state #2218, ToC: links to markdown headings #1478.
• Fixed inconsistent category title rendering, Small inconsistency in rendering category names #2196
• A leading v will be stripped off versions in package.json, the --includeVersion flag now checks if the prefix "v" already exists… #2212