Cross-package references in monorepository not working #1835

nlepage · 2022-01-04T16:06:25Z

Search terms

monorepository entrypointStrategy packages reference

Expected Behavior

Cross-package references should "work" when generating documentation for several packages in a monorepository (using yarn workspaces), with an entrypointStrategy set to packages.

Actual Behavior

Cross-package references yield a warning:

A, defined at packages/a/lib/index.d.ts:3, is referenced by @typedoc-packages-missing-export/b.B.__type.a but not included in the documentation.

And the resulting documentation does not have hyperlinks for such references.

Steps to reproduce the bug

Here is an example repository to reproduce the bug: https://github.com/nlepage/typedoc-packages-missing-export

Environment

Typedoc version: 0.22.10
TypeScript version: 4.5.4
Node.js version: 14.17.0
OS: Linux

The text was updated successfully, but these errors were encountered:

nlepage · 2022-01-04T16:07:44Z

I'm willing to help resolve the issue, however I don't have enough knowledge of TypeDoc in order to guess where to start looking.

Gerrit0 · 2022-01-08T19:32:37Z

This happens for the same reason it happens with project references. TypeDoc creates a new program for each monorepo, and symbols between programs are completely separate... but references are resolved by symbol equality.

I think this could be resolved by changing symbols so that they are compared by source location (with mapping... so declarationMap would have to be turned on), but haven't gotten around to trying to make that work yet.

nlepage · 2022-01-09T11:09:22Z

Thanks for the hint, I'll give it a try.

nlepage · 2022-01-12T16:50:25Z

Hey @Gerrit0

I made a plugin to solve the problem: nlepage/typedoc-plugin-resolve-crossmodule-references.
Not sure about all of it, but it works fine for the basic cases.
Here is an example of generated documentation where types from a module a reference a type B from a module b.
It is published on npm.

I'm not sure if it can help with project references as I'm not familiar with these.

Let me know if it is something you would like to integrate in TypeDoc itself.
It needs only one new dependency (plus a transitive one): convert-source-map.

Gerrit0 · 2022-01-30T16:49:35Z

I think that's definitely a promising path forward! I'm probably not going to have time this weekend to look at it in as much detail as it deserves, but it's something I'm absolutely interested in pursuing. I'd like to avoid the extra resolution step if possible, (by storing reference targets by file/location?)

phihochzwei · 2022-07-19T12:59:54Z

@nlepage Are there any prerequisite I need to know or settings made to get your plugin working? I just installed and tried but unfortunately it did not work for me :(

nlepage · 2022-07-22T07:21:42Z

@nlepage Are there any prerequisite I need to know or settings made to get your plugin working? I just installed and tried but unfortunately it did not work for me :(

Hey @phihochzwei
Seems the plugin I wrote crashes with the latest version of typedoc, as a workaround you can try downgrading typedoc to v0.22.18.
I'll try to fix the plugin to make it work with the latest version of typedoc.

nlepage · 2022-07-22T09:56:46Z

@nlepage Are there any prerequisite I need to know or settings made to get your plugin working? I just installed and tried but unfortunately it did not work for me :(

@phihochzwei I published a new release of the plugin, let me know if it works for you.

Typedoc has issues with monorepo support using lots of memory. See #356 and TypeStrong/typedoc#1835. This avoids the crash in two different ways: 1. I increased the node heap size to 8192 which seems to be sufficient to make the build succeed for now. 2. For now I am pointing typedoc at the source code directly rather than using the monorepo support. This uses a lot less memory and is a lot faster.

fryorcraken · 2022-12-20T13:08:51Z

Is the plugin still the way to go?

Gerrit0 · 2022-12-20T14:17:34Z

At this point, yes. I'm getting somewhat closer to bringing this functionality into TypeDoc itself, but that will be a part of 0.24 most likely.

Tschakki · 2022-12-28T17:18:40Z

@nlepage Just wanted to mention the plugin works great for me, thanks. :) Except that it doesn't identify the @link references to other modules for me unfortunately.

nlepage · 2022-12-28T18:22:24Z

@Tschakki I'll have a look, could you open an issue on the plugin's repository thanks https://github.com/nlepage/typedoc-plugin-resolve-crossmodule-references

### What was the problem? This PR resolves #7901 Please note there is currently a bug in TypeDoc with the effect that references between packages are not working, see TypeStrong/typedoc#1835 ### How was it solved? - Export relevant data structures - Add relevant code comments - Add typedoc to the dev dependencies - Add typedoc options to the `package.json` in each package. - Create typedoc.json and include required options for generating the docs properly. - Create new folder `docs/typedoc` to store generated typeDocs ### How was it tested? `cd lisk-sdk/` `npx typedoc` ### Result https://liskhq.github.io/lisk-docs/lisk-sdk/v6/references/typedoc/modules/_liskhq_lisk_transactions.html

I have been struggling to keep track of what Perses exports from the various UI packages, which can make it tricky to figure out breaking changes when things are refactored. Typedoc does a nice job evaluating the entry point and creating documentation, so that seemed like a low effort way to get this information. In the short term, storing these as artifacts in github actions runs. Longer-term, we could potentially publish these in github pages alongside storybook (good at documenting React components) to provide documentation for the non-component utilities, types, etc. that Perses provides. It is notable that typedoc isn't great at handling cross-package dependencies at this time, so there are some limitations to what we're getting. We can watch this issue to see when this is improved. TypeStrong/typedoc#1835 Signed-off-by: Julie Pagano <julie.pagano@chronosphere.io>

Gerrit0 · 2023-04-08T22:47:42Z

v0.24.0 made a ton of changes, including a fix for this. Types are now serialized with their location rather than relying on object identity, and therefore can be resolved even across packages

imranbarbhuiya · 2023-04-16T00:16:40Z

v0.24.0 made a ton of changes, including a fix for this. Types are now serialized with their location rather than relying on object identity, and therefore can be resolved even across packages

I don't think it's working. U can check this table using the plugin in older version of typedoc https://tagscript.js.org/typedoc-api/plugins/plugin-discord/classes/BaseTransformer#parameters-1 vs current one https://tag-script-git-renovate-all-minor-patch-imranbarbhuiya.vercel.app/typedoc-api/plugins/plugin-discord/classes/BaseTransformer#parameters-1

Also an unrelated issue so lmk if I should create a new issue for this but when using links like {@link discord.js!}, and adding it's link using typedoc-plugin-external-link, it works but tsdoc eslint warns about using ! also it renders the ! in final website too but removing ! doesn't works and tsdoc warns that the link wasn't resolved

Gerrit0 · 2023-04-16T00:34:30Z

I'm going to have to ask for a new issue with a minimal reproduction for both of those. I don't have time to dig through big projects for a bug.

imranbarbhuiya · 2023-04-16T00:42:06Z

ok thanks for the reply, i'll do it today

Dayday10 · 2023-04-16T02:49:42Z

I'm going to have to ask for a new issue with a minimal reproduction for both of those. I don't have time to dig through big projects for a bug.

Thanks for all your hard work.

Dayday10 · 2023-04-16T02:50:25Z

Two 👍

nlepage · 2023-04-26T10:18:24Z

typedoc-plugin-resolve-crossmodule-references is now archived and deprecated on npm, thanks for all your hard work @Gerrit0 !

nlepage added the bug Functionality does not match expectation label Jan 4, 2022

fb55 mentioned this issue Mar 7, 2022

docs: Introduce Typedoc inikulin/parse5#443

Merged

WHenderson mentioned this issue Mar 19, 2022

Broken package nlepage/typedoc-plugin-resolve-crossmodule-references#1

Closed

This comment was marked as outdated.

Sign in to view

Gerrit0 mentioned this issue Jul 19, 2022

Generating docs for libs in NX Monorepo #2005

Closed

Gerrit0 mentioned this issue Jul 27, 2022

Why is there a <internal> namespace for modules? #2018

Closed

cocopon mentioned this issue Aug 13, 2022

Update dependencies cocopon/tweakpane#420

Merged

Gerrit0 mentioned this issue Oct 23, 2022

When using packages allow allow linking to types between different packages #1612

Closed

This was referenced Nov 15, 2022

OOM on large monorepo project #1606

Closed

Investigate 'Javascript heap out of memory' error act-now-coalition/act-now-packages#356

Closed

mikelehen mentioned this issue Nov 15, 2022

Reenable typedoc with workarounds to avoid out-of-memory crash. act-now-coalition/act-now-packages#399

Merged

erickzhao mentioned this issue Nov 25, 2022

docs(api): slim down generated TypeDoc output electron/forge#3096

Closed

Tschakki mentioned this issue Dec 20, 2022

Add TypeDoc to lisk-transactions LiskArchive/lisk-sdk#7909

Merged

Gerrit0 added this to the v0.24 milestone Mar 11, 2023

juliepagano mentioned this issue Mar 30, 2023

[IGNORE] Add simple typedoc setup perses/perses#1056

Merged

4 tasks

whizzzkid mentioned this issue Apr 5, 2023

Support typedoc-plugin-resolve-crossmodule-reference ipfs/aegir#1227

Open

Gerrit0 closed this as completed Apr 8, 2023

Tschakki mentioned this issue Apr 11, 2023

Update TypeDoc to version 24 LiskArchive/lisk-sdk#8351

Closed

nlepage mentioned this issue Apr 24, 2023

TypeError: type.getSymbol is not a function nlepage/typedoc-plugin-resolve-crossmodule-references#17

Closed

danisharora099 mentioned this issue Aug 3, 2023

feat: improve description of interfaces and API docs waku-org/js-waku#1424

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Cross-package references in monorepository not working #1835

Cross-package references in monorepository not working #1835

nlepage commented Jan 4, 2022

nlepage commented Jan 4, 2022

Gerrit0 commented Jan 8, 2022

nlepage commented Jan 9, 2022

nlepage commented Jan 12, 2022 •

edited

Loading

Gerrit0 commented Jan 30, 2022

This comment was marked as outdated.

phihochzwei commented Jul 19, 2022

nlepage commented Jul 22, 2022

nlepage commented Jul 22, 2022

fryorcraken commented Dec 20, 2022

Gerrit0 commented Dec 20, 2022

Tschakki commented Dec 28, 2022

nlepage commented Dec 28, 2022

Gerrit0 commented Apr 8, 2023

imranbarbhuiya commented Apr 16, 2023

Gerrit0 commented Apr 16, 2023

imranbarbhuiya commented Apr 16, 2023

Dayday10 commented Apr 16, 2023

Dayday10 commented Apr 16, 2023

nlepage commented Apr 26, 2023

Cross-package references in monorepository not working #1835

Cross-package references in monorepository not working #1835

Comments

nlepage commented Jan 4, 2022

Search terms

Expected Behavior

Actual Behavior

Steps to reproduce the bug

Environment

nlepage commented Jan 4, 2022

Gerrit0 commented Jan 8, 2022

nlepage commented Jan 9, 2022

nlepage commented Jan 12, 2022 • edited Loading

Gerrit0 commented Jan 30, 2022

This comment was marked as outdated.

phihochzwei commented Jul 19, 2022

nlepage commented Jul 22, 2022

nlepage commented Jul 22, 2022

fryorcraken commented Dec 20, 2022

Gerrit0 commented Dec 20, 2022

Tschakki commented Dec 28, 2022

nlepage commented Dec 28, 2022

Gerrit0 commented Apr 8, 2023

imranbarbhuiya commented Apr 16, 2023

Gerrit0 commented Apr 16, 2023

imranbarbhuiya commented Apr 16, 2023

Dayday10 commented Apr 16, 2023

Dayday10 commented Apr 16, 2023

nlepage commented Apr 26, 2023

nlepage commented Jan 12, 2022 •

edited

Loading