Support for merging modules together with @module

[krisztianb]

Search terms

module index page

Question

This is related to my typedoc plugin which can merge the content of modules and using it on a monorepo project.

Without using the plugin on the monorepo project the main page looks like this:

With using the plugin to merge modules (in this case they equal the projects having the same name) the module page looks like this:

As you can see class "C" is missing in the index but shows up in the navigation on the left. The question is why?

What I think the problem is:

When the plugin is used with TypeDoc's entryPointStrategy set to packages the plugin is listening to the even Application.EVENT_PROJECT_REVIVE and merges the modules when this event is emitted by TypeDoc: https://github.com/krisztianb/typedoc-plugin-merge-modules/blob/master/src/plugin.ts#L63

As I understand the code TypeDoc uses a CategoryPlugin to create the model used for rendering the module index. It seems to me that the index is generated before the plugin is merging the modules. Therefore the index is outdated in the end. Do you think that this is the case? If so how could this be fixed?

How to reproduce

I added automated tests to the plugin repo which can be used to reproduce the problem: https://github.com/krisztianb/typedoc-plugin-merge-modules/tree/master/test/merge-module-monorepo

You can use npm install followed by npm run build and npm test to run the tests and see the result.

[Gerrit0]

Your guess at what the problem is is exactly correct, categorization happens during Converter.EVENT_RESOLVE_END, so it has actually already been done for each individual project. Once projects are merged together, the existing categories are assumed to be correct.

Fixing this is going to be somewhat annoying. @category tags are removed during categorization, and TypeDoc doesn't re-run categorization during project revival. You probably get 90% of the way there by manually checking and merging module.categories (should also check for module.groups to ensure all values of the navigation option work as expected)

... but that still leaves the other 10%. TypeDoc uses the sort option to decide how to sort reflections within modules/groups/categories, and the sorting function isn't exposed (I guess this is an argument that it should be, which means I have to figure out where to put it...) seems kind of weird to directly export getSortFunction...

[krisztianb]

Thanks for your feedback. I agree that exporting the sort function seems kind of strange. Maybe the functionality of the plugin should be part of TypeDoc itself?

Another solution could be to somehow invoke the sorting of the categories from the plugin. So the plugin can merge the categories and then get them sorted by TypeDoc.

[Gerrit0]

I haven't a reason for something like this to be included in TypeDoc itself, looking at the use cases in the plugin's readme - generating documentation for applications is something that's never made sense to me... why not just look at the code? Can't merging modules be done already via re-exports, so that the documentation actually matches the library exports?

[krisztianb]

I haven't a reason for something like this to be included in TypeDoc itself, looking at the use cases in the plugin's readme - generating documentation for applications is something that's never made sense to me... why not just look at the code?

I see the point. We use it to document the code for new employees so that they can get a quicker overview (with class diagrams) of the code.

Can't merging modules be done already via re-exports, so that the documentation actually matches the library exports?

I guess it can. But you have to write additional code just for the documentation.

[j-perezr]

Thanks for your feedback. I agree that exporting the sort function seems kind of strange. Maybe the functionality of the plugin should be part of TypeDoc itself?

Another solution could be to somehow invoke the sorting of the categories from the plugin. So the plugin can merge the categories and then get them sorted by TypeDoc.

Totally please :) specially in monorepos

[j-perezr]

I haven't a reason for something like this to be included in TypeDoc itself, looking at the use cases in the plugin's readme - generating documentation for applications is something that's never made sense to me... why not just look at the code? Can't merging modules be done already via re-exports, so that the documentation actually matches the library exports?

I can tell our specific use case.
We have a library in a monorepo divided by contexts, like auth or region.
Inside each context we have different packages, like in hexagonal architecture. This is to take full advantage of NX, tool to handle the monorepo.
We then expose everything through a single entry point but that entry point cannot be used to generate the typings.

Repo
   |- auth
   |     | - domain
   |     |        | - package.json
   |     | - application
   |              | - package.json
   | - entry
        | - auth

Some modules are compiled to js due to technical restrictions and in 'entry' there is no access to the typescript source, so I can only generate the doc for each independent package, but in the typedoc output I don't want to separate domain and application, I only want to have auth.

[Gerrit0]

I don't much like it, but that's a pretty good reason for this being in typedoc itself.