Usage with monorepo doesn't seem to work

[j-perezr]

Hi! First of all thanks for your plugin :)

We are having issues working with typedoc@0.24 and typedoc-plugin-merge-modules in a monorepo.

In the typedoc@0.24 release, the author rebuilt the way typedoc works and how it builts the documentation for monorepos.

Currently, we are not able to make typedoc-plugin-merge-modules work in a monorepo with multiple packages

This worked with typedoc@0.23 and the previous version of the plugin

Expected Behavior

The documentation generated for all the packages properly merge the different packages with the same @module @mergeTarget tags

Current Behavior

Modules are not merged and are shown independently.

Steps to Reproduce

I will provide a repo with an example, we use Nx for the monorepo.

We have these projects in Nx each one with his own package.json

Typedoc@0.24 requires to split the configurations, we created a typedoc.json in both of them

the index.ts (entry point configured for typedoc) has the comments

but the result is

and here the typedoc global config

I will provide an example repository this afternoon :)

[krisztianb]

Hi. I must have missed these changes when I looked at the change log of TypeDoc 0.24. If you can provide an example repository I can look into this when I find the time.

[j-perezr]

Hello! thank you for your quick response. Here you have https://github.com/jperezruiz/typedoc-024-plugin-merge-modules

In the main branch I have created the example using typedoc@0.24 and typedoc-plugin-merge-modules@4.1.0

I have also created a branch called 0.23 with typedoc@0.23 and typedoc-plugin-merge-modules@4.0.1

You can execute typedoc by running npm run build:docs and launch a preview with npm run serve:docs.

In the 0.23 branch you will see

And in the main branch

[krisztianb]

Thank you for the test repository.

The problem should be fixed in version 5.0.0 that I just released on NPM. 🎉

The problem was that TypeDoc 0.24 creates a separate converter for every package when using the entry point strategies "merge" or "package" which resulted in the merge getting called too early. I had to change the TypeDoc events the plugin subscribes to in order to get it working. Unfortunately while doing this I also had to drop support for TypeDoc version 0.23 as that version doesn't include the new events. 😞

Please report back after you updated to and tested the new version so that we can close this issue.

[j-perezr]

Thank you very much! Your plugin is amazing, to the point that it should be part of typedoc

[krisztianb]

Thanks. I also think that this functionality should be part of TypeDoc. Maybe someday it will be.

[j-perezr]

I confirm is working now, thank you!

[j-perezr]

Hi @krisztianb I just discovered something about the merging :( To give you context, in my case, I have a module for the type aliases and another for the actual implementation, it seems that the merge is partially done, because the members appears in the side nav, but it doesn't appear in the index, the main page with the README.

I will update the repo with the example

[krisztianb]

Hi. Ok. Please post the current behaviour and how you would like it to be. Then I can take a look.

[j-perezr]

Hi! thanks for your fast response ^^ I updated the same example repo.

Here the result using 0.23 and typedoc-plugin-merge-modules@4

And here using 0.24 and typedoc-plugin-merge-modules@5

The merge is well done, all declarations appear in the sidenav and I can navigate to them: but only the declarations from the first module appear in the index

[krisztianb]

The good news: I can reproduce the problem and added an automated test to the plugin's repo that currently fails because of this issue: https://github.com/krisztianb/typedoc-plugin-merge-modules/blob/master/test/merge-module-monorepo/test.cy.ts#L32

The (somewhat) bad news: I'm not sure what the problem is. It seems to be unrelated to the plugin's code itself. Either it is a bug in TypeDoc or the plugin is executed too late after the index has already been generated by TypeDoc. I created an issue for this in the TypeDoc repo: https://github.com/TypeStrong/typedoc/issues/2281

Hopefully Gerrit will be able to take a look at this and hint me into the right direction.

[j-perezr]

Hi! Thank you very much, I hope typedoc devs can take a look at it.

[krisztianb]

It looks like that this can't be solved 100% correctly for the time being.

Since the problem is that the index is generated before the plugin merges the modules, what we could do is to "recreate" the index on our own after the merge. The only problem is as Gerrit pointed out, that the sort order of the index entries can be specified in the config and we don't have access to the sorting function that is used to do the sort.

Are you using any kind of specific sort settings in your config? If not we could simply implement an alphabetical sorting. Even if it is not always "correct" it is better than having an incomplete index.

[j-perezr]

Hi! No, I'm not using the sort config. Re-creating the index sounds good as a solution for now with the restriction of the sorting.

[krisztianb]

Hi. I released version 5.0.1 which also merges categories and groups and sorts them alphabetically. Please give me feedback if it is working correctly for you. Thanks.

[j-perezr]

Hi @krisztianb , Thank you very much for all the effort, I really appreciate it. I will check it and let you know.

[j-perezr]

Hi! I confirm that works nicely 👏 Again, thank you very much for your effort