Build documentation for individual package in monorepository

[shivjm]

With 0.21, TypeDoc now has a --packages option, which I think could be used instead of entry points. It does the "main" resolution from package.json, handles monorepos that use npm/yarn workspaces, and just works better for most use cases...

Originally posted by @Gerrit0 in #1485 (comment)

I tried using this for shivjm/remark-extensions, which is a monorepo. It does work and I get a list of modules, but the process is complicated by the fact that I really only want to update the docs for one package at a time. If I just run typedoc --entryPointStrategy packages, it tries to build the documentation for all the packages in the repository, including all the unreleased changes to other packages. If I specify a single package as the target, it can’t link to its siblings, since those aren’t being processed.

This is the sort of thing I’d like to be able to do:

1. Check out my current gh-pages.
2. Regenerate just the documentation for a single package, while still being able to link to sibling packages.
3. Build/update a root index.html that provides a list of (linked) packages and versions.

[Gerrit0]

This would be really nice to do, there's quite a lot of architectural changes needed in order for this to be able to work well... I think it needs to be some combination of #1646, #1180, and a third issue to merge previously generated projects to do this properly.

It isn't necessarily safe to re-render just one project, since removing something might result in a broken link, or if something changes from, say, an interface to an abstract class, the URL would change.

[shivjm]

This would be really nice to do, there's quite a lot of architectural changes needed in order for this to be able to work well... I think it needs to be some combination of #1646, #1180, and a third issue to merge previously generated projects to do this properly.

Yeah, I can imagine there’s a lot to it.

It isn't necessarily safe to re-render just one project, since removing something might result in a broken link, or if something changes from, say, an interface to an abstract class, the URL would change.

That’s something I was wondering about. I don’t have a good solution. It isn’t TypeDoc’s responsibility (or a good idea, either, for that matter) to reach into the history and generate the docs for each package at a given revision, but then how does one avoid generating documentation for un-released changes to sibling packages in the same revision?

[Gerrit0]

Right now, there's not really a way to do it besides checking out parts of the tree to the released commit when building docs, which is a horrible solution, but...

[okikio]

Right now, there's not really a way to do it besides checking out parts of the tree to the released commit when building docs, which is a horrible solution, but...

What if you set it up, for watch, or add a setting where devs can specify that monorepo packages don't talk to each other?

[DaSchTour]

I'm not sure if that's 100% related. I tried to use typedoc in a NX monorepo. I added "entryPointStrategy": "packages" to my typedoc.json and referenced the tsconfig.base.json which also includes the paths to the different packages. My expectation was, that the name from package.json or at least the displayName would show up as module in the documentation. But actually the name from the base package.json was taken and only the first package from the list of entryPoints was added to the documentation.

[Gerrit0]

v0.24.0 has released with the necessary tools to do this. There is now --entryPointStrategy merge, which can take JSON files previously generated with TypeDoc's --json option and merge them together to create a single project.

[michaeltford]

@Gerrit0 that is great news. Is there an example of this? I am trying to combine multiple packages from a mono repo? I am referencing your repo https://github.com/Gerrit0/typedoc-packages-example but it's using the 'packages' strategy.

[Gerrit0]

I've updated that repo with the manual option now, it boils down to this:

# Or for more control over when each package is built, we can manually build each
# package and save the output of --json
# Cross-package links will be invalid here, they will be validated when merging
npx typedoc --json docs-json/bar.json --options packages/bar/typedoc.json --validation.invalidLink false
npx typedoc --json docs-json/baz.json --options packages/baz/typedoc.json --validation.invalidLink false
npx typedoc --json docs-json/foo.json --options packages/foo/typedoc.json --validation.invalidLink false
# Merge previously generated documentation together into a site
npx typedoc --entryPointStrategy merge "docs-json/*.json"

[shivjm]

I didn’t get around to trying it for a long time, but I wanted to confirm that the new feature and @Gerrit0’s suggestion in the last comment worked perfectly for my case too. Thank you for implementing this extremely useful feature.