marcj / typedoc-plugin-lerna-packages

A plugin for Typedoc that groups all Lerna packages into own TS module

typedoc-plugin-lerna-packages

A plugin for Typedoc that groups all Lerna packages into own TS module. Normally Typedoc handles each file as a module, this isn't correct for lerna packages, as each package should be treated as a module. This plugins handles that. Also if you have a README.md in your package folder, it will be used as comment for that module.

Example Demo: https://marshal.marcj.dev/

Example source code: https://github.com/marcj/marshal.ts

Just install it and type typedoc:

npm i -D typedoc-plugin-lerna-packages typedoc@~0.16
# yarn add -D typedoc-plugin-lerna-packages [email protected] --tilde

npx typedoc
# yarn typedoc

Example typedoc.js in your root folder

module.exports = {
  mode: 'modules',
  out: 'docs',
  exclude: ['**/node_modules/**', '**/*.spec.ts'],
  name: 'MY NAME',
  excludePrivate: true
};

Options

In typedoc.js you can add following extra config values to change the behavior of this plugin.

module.exports = {
  //...

  //exclude packages from being generated
  lernaExclude: ['@vendor/integration-tests', '@vendor/examples']
};

Development

When you work on this package you should link to it in a other lerna repo, and then execute following command to make generation working:

rm -rf docs && NODE_PRESERVE_SYMLINKS=1 ./node_modules/.bin/typedoc

typedoc-plugin-lerna-packages's Issues

readme option conflicts with typedoc readme option.

Typedoc already uses readme option to set readme as whole project index.html. (https://typedoc.org/guides/options/#readme) I'm using this option in my project's documentation.
Since you introduced this option in this plugin, index pages for lerna packages are gone. Only classes list is produced.
When i'm unseting this option everything is fine, index pages for packages are produced from corresponding readme, but whole project first index.html is wrong...

Here is the project: https://github.com/icek/ash
And documentation: https://icek.github.io/ash/

Modules getting bundled but have extra greyed out headings

Firstly thanks for this plugin, it looks like it's going to be really useful as more and more people use Lerna and mono repos in general!

I'm using the plugin succesfully (mostly) on my open source project, Dobby, it's definitely grouping the files within into modules but the weird thing is it seems to be leaving behind a greyed out link to the files:

The full link to the docs is here, I would appreciate if you could take a look and see if I'm doing something obviously wrong? I did look over your example source code but from what I'm seeing it should work

Illegal Operation on a directory, read

When trying to run typedoc with the plugin installed, the docs cannot be generated and the command fails with the following trace:

> yarn typedoc .
yarn run v1.22.4
$ C:\PATH\node_modules\.bin\typedoc .
Loaded plugin C:\PATH\node_modules\typedoc-neo-theme
Loaded plugin C:\PATH\node_modules\typedoc-plugin-lerna-packages

Using TypeScript 3.7.5 from C:\PATH\node_modules\typedoc\node_modules\typescript\lib
Lerna packages found {
  '@scope/one': 'packages/one',
  '@scope/two': 'packages/two',
  '@scope/three': 'packages/three',
  '@scope/four': 'packages/four',
  '@scope/five': 'packages/five',
  '@scope/six': 'packages/six',
  '@scope/seven': 'packages/seven'
}
internal/fs/utils.js:230
    throw err;
    ^

Error: EISDIR: illegal operation on a directory, read
    at Object.readSync (fs.js:564:3)
    at tryReadSync (fs.js:349:20)
    at Object.readFileSync (fs.js:386:19)
    at LernaPackagesPlugin.onBeginResolve (C:\PATH\node_modules\typedoc-plugin-lerna-packages\dist\plugin.js:102:39)
    at triggerEvents (C:\PATH\node_modules\typedoc\dist\lib\utils\events.js:128:43)
    at triggerApi (C:\PATH\node_modules\typedoc\dist\lib\utils\events.js:110:13)
    at eventsApi (C:\PATH\node_modules\typedoc\dist\lib\utils\events.js:21:18)
    at Converter.trigger (C:\PATH\node_modules\typedoc\dist\lib\utils\events.js:264:13)
    at Converter.resolve (C:\PATH\node_modules\typedoc\dist\lib\converter\converter.js:180:14)
    at Converter.convert (C:\PATH\node_modules\typedoc\dist\lib\converter\converter.js:91:30) {
  errno: -4068,
  syscall: 'read',
  code: 'EISDIR'
}
error Command failed with exit code 1.
info Visit https://yarnpkg.com/en/docs/cli/run for documentation about this command.

I tried uninstalling the neo theme and using typedoc 0.16 and 0.17, to no avail

Typedoc Version:

> yarn typedoc --version
yarn run v1.22.4
$ C:\PATH\node_modules\.bin\typedoc --version
Loaded plugin C:\PATH\node_modules\typedoc-plugin-lerna-packages

TypeDoc 0.16.11
Using TypeScript 3.7.5 from C:\path\node_modules\typedoc\node_modules\typescript\lib
Done in 3.17s.

Node Version:

> node --version
v12.18.2

typedoc.json:

{
  "name": "NAME",
  "mode": "modules",
  "out": "docs",
  "ignoreCompilerErrors": "false",
  "preserveConstEnums": "true",
  "exclude": ["**/node_modules/**", "*.spec.ts"],
  "stripInternal": "false"
}

Also tried with a typedoc.js instead but this didn't change anything

The PR #23 is not in the 0.3.0 build

Hi guys, the fix you made here #23 (comment) is not in the latest build 0.3.0 for all others who cannot wait for this issue to be published use this package https://www.npmjs.com/package/woss-typedoc-plugin-lerna-packages it is the SAME as this master but has the fix in the build

please when you guys make a build and publish it, let me know and i will remove the package 🙌

Error on first run

I configured typedoc.json at the root of my lerna project.
It seemed to recognize all the project packages and locations, but failed on the following issue.

Log:

C:\{project_path}\node_modules\typedoc-plugin-lerna-packages\dist\plugin.js:58
const copyChildren = context.project.children.slice(0);
^

TypeError: Cannot read property 'slice' of undefined
at LernaPackagesPlugin.onBeginResolve (C:\{project_path}\node_modules\typedoc-plugin-lerna-packages\dist\plugin.js:58:55)
at triggerEvents (C:\{project_path}\node_modules\typedoc\dist\lib\utils\events.js:128:43)
at triggerApi (C:\{project_path}\node_modules\typedoc\dist\lib\utils\events.js:110:13)
at eventsApi (C:\{project_path}\node_modules\typedoc\dist\lib\utils\events.js:21:18)
at Converter.trigger (C:\{project_path}\node_modules\typedoc\dist\lib\utils\events.js:264:13)
at Converter.resolve (C:\{project_path}\node_modules\typedoc\dist\lib\converter\converter.js:180:14)
at Converter.convert (C:\{project_path}\node_modules\typedoc\dist\lib\converter\converter.js:91:30)
at CliApplication.convert (C:\{project_path}\node_modules\typedoc\dist\lib\application.js:72:39)
at CliApplication.bootstrap (C:\{project_path}\node_modules\typedoc\dist\lib\cli.js:45:34)
at Object. (C:\{project_path}\node_modules\typedoc\bin\typedoc:5:5)
error Command failed with exit code 1.

Cannot find name WebAssembly

Error: .../as-pect/packages/core/src/util/IAspectExports.ts(66)
 Cannot find namespace 'WebAssembly'.
Error: .../as-pect/packages/core/src/util/wasmTools.ts(56)
 Cannot find name 'WebAssembly'.
Error: .../as-pect/packages/core/src/util/wasmTools.ts(57)
 Cannot find name 'WebAssembly'.

Mostly unsure what to do about this since that definition is in lib.dom.d.ts and it worked in version 0.2.2.

Hoping to find a solution

Just wanted to say: Thank you!

This plugin is amazing!

I've got over 20 packages now (and not even close to finishing) and TypeDoc (with no alternative to use) became rather useless at this scale. Yeah, everything was documented, but nothing was able to be found.

So, thanks!

Generated docs is empty

TypeDoc generates empty documentation.

I have installed TypeScript 4.1.5 (latest), TypeDoc 0.17.8 and typedoc-plugin-lerna-packages 0.3.1.

The project has the monorepo structure with all packages under packages folder. Here is the lerna.json configuration file:

{
  "version": "independent",
  "npmClient": "npm",
  "stream": true,
  "packages": ["packages/*"],
  "publishConfig": {
    "access": "restricted"
  },
  "command": {
    "bootstrap": {}
  }
}

The plugin correctly find the lerna packages:

Configuration file (typedoc.json):

{
  "name": "API",
  "mode": "modules",
  "out": "docs",
  "exclude": [
    "**/node_modules/**",
    "**/tests/**",
    "**/*.spec.ts",
    "**/*.test.ts",
    "jest.config.ts",
    "jest.config.common.ts",
    "**/jest.config.ts"
  ]
}

HTML docs page:

I'm struggling with this problem for hours and I don't know what is wrong.

Anyone have a suggestion?

Thanks

PS: The overall project structure is a copy of: https://github.com/carlocorradini/graphmarket

Package fails to find package on Windows

typedoc-plugin-lerna-packages/plugin.ts

Line 71 in 6a315f4

const findLernaPackageForChildOriginalName = (path: string): string => {

Logging out the variables reveals the problem.

for (const i in this.lernaPackages) {
  if (!this.lernaPackages.hasOwnProperty(i))
    continue;
  console.log(i);
  const packagePath = path_1.join(cwd, this.lernaPackages[i]) + '/';
  console.log("packagePath:", packagePath);
  console.log("path:", path);
  if (-1 !== (path + '/').indexOf(packagePath)) {
  console.log("fit", fit);
  if (i.length > fit.length) {
    fit = i;
  }
}

@as-pect/cli
packagePath: C:\Users\jtenner\Desktop\projects\as-pect\packages\cli/
path: C:/Users/jtenner/Desktop/projects/as-pect/packages/cli/src/help.ts
@as-pect/core
packagePath: C:\Users\jtenner\Desktop\projects\as-pect\packages\core/
path: C:/Users/jtenner/Desktop/projects/as-pect/packages/cli/src/help.ts

As you can see, the strings aren't normalized for windows users. This can be fixed by simply calling path.normalize() on the packagePath and the path object.

Would you like me to submit a pull request?

TypeScript version is not updated (using 3.2.4)

Hey this should probably use the local typescript version.

Not sure how to change this. Any advice?

Incompatible with Typedoc v0.16.x

Running typedoc v0.16.7 with this plugin produces the following error:

$ typedoc
Error: The plugin /Users/favna/workspace/air-node-packages/node_modules/typedoc-plugin-lerna-packages could not be loaded.

TypeError: component_1.Option is not a function
    at Object.<anonymous> (/Users/favna/workspace/air-node-packages/node_modules/typedoc-plugin-lerna-packages/plugin.js:138:17)
    at Module._compile (internal/modules/cjs/loader.js:1139:30)
    at Object.Module._extensions..js (internal/modules/cjs/loader.js:1159:10)
    at Module.load (internal/modules/cjs/loader.js:988:32)
    at Function.Module._load (internal/modules/cjs/loader.js:896:14)
    at Module.require (internal/modules/cjs/loader.js:1028:19)
    at require (internal/modules/cjs/helpers.js:72:18)
    at Object.<anonymous> (/Users/favna/workspace/air-node-packages/node_modules/typedoc-plugin-lerna-packages/index.js:1:14)
    at Module._compile (internal/modules/cjs/loader.js:1139:30)
    at Object.Module._extensions..js (internal/modules/cjs/loader.js:1159:10)

This is likely because typedoc changed their decorators in recent versions.

Supporting Typedoc v0.20.x

Typedoc did it once again, they released a new version that breaks this extremely useful plugin in many ways. To keep up to date with things it would be nice if this library would be updated to support the latest Typedoc.

For the migration guide for Typedoc see: https://github.com/TypeStrong/typedoc/releases/tag/v0.20.0

Shared type definition makes doc build interrupt.

My project folder structure just like

MyProject
├── packages
│   ├── a
│   ├── b
│   └── c
└──  types
    ├── shared-type-1.ts
    └── shared-type-2.ts

When doc generation for packages folder, import the type definition from types throws a error.

added some logs for tracking

packagePath: /Users/xuqingkuang/MyProject/packages/a/
path: /Users/xuqingkuang/MyProject/types/shared-type-1.ts
packagePath: /Users/xuqingkuang/MyProject/packages/b/
path: /Users/xuqingkuang/MyProject/types/share-type-1.ts
fit: ""
/Users/xuqingkuang/MyProject/node_modules/typedoc-plugin-lerna-packages/plugin.js:73
                throw new Error(`No lerna package found for ${path}`);
                ^

Error: No lerna package found for /Users/xuqingkuang/MyProject/types/share-type-1.ts
    at findLernaPackageForChildOriginalName (/Users/xuqingkuang/MyProject/node_modules/typedoc-plugin-lerna-packages/plugin.js:73:23)
    ...

I located the code at: https://github.com/marcj/typedoc-plugin-lerna-packages/blob/master/plugin.ts#L84

It will check import, and throw a error when the import is not in packages folder

My typedoc.js content:

module.exports = {
  name: 'MyProject',
  mode: 'modules',
  out: 'docs/en-US',
  allowJs: true,
  ignoreCompilerErrors: true,
  excludePrivate: true,
  excludeProtected: true,
  skipInternal: true,
  exclude: [
    '**/node_modules/**',
    '**/__tests__/*.test.*',
  ],
  lernaExclude: [
    '@localTypes/shared-type-1',
    '@localTypes/shared-type-2',
  ],
  plugin: [
    'typedoc-plugin-markdown',
    'typedoc-plugin-no-inherit',
    'typedoc-plugin-lerna-packages',
  ],
};

tsconfig.json defined @localTypes as alias to types folder, but the lernaExclude option seems doesn't work.

Sorry for my Engilsh is bad, hope you can understand.