Make basePath configurable

[jan-molak]

Search terms

Monorepo, lerna, nrwl, fileName

Expected Behavior

Given a mono-repo with modules under a common directory, for example:

packages
- module-A
  - src
    - index.ts
- module-B
  - src
    - index.ts

I'd expect fileName discovered for index.ts in module-A (and module-B) to include the common directory name, so packages/module-A/src/index.ts instead of just module-A/src/index.ts

Actual Behavior

To my understanding, when TypeDoc parses the sourcecode, it calls getCommonDirectory to automatically determine the root directory.

However, for mono-repos that follow the structure recommended by Lerna (with all the public modules under packages), the fileName determined by TypeDoc is incorrect since it misses the top-level sub-directory name.

This then has a knock-on effect on other projects such as docusaurus-plugin-typedoc-api, which use fileName to determine the location of the file in the GitHub repository - see milesj/docusaurus-plugin-typedoc-api#39

Steps to reproduce the bug

See above

Proposed solution

It feels like making the basePath in onBeginResolve configurable could solve this problem:

    private onBeginResolve(context: Context) {
-        this.basePath = getCommonDirectory([...this.fileNames]);
+        this.basePath = this.basePath || getCommonDirectory([...this.fileNames]);
        for (const file of context.project.files) {
            const fileName = (file.fileName = normalizePath(
                relative(this.basePath, file.fileName)
            ));
            this.fileMappings[fileName] = file;
        }
    }

Environment

• Typedoc version: 0.22.13
• TypeScript version: 4.6.3
• Node.js version: 16.13.1
• OS: macOS 12.3.1

[Gerrit0]

The specific problem you're running into I believe will be resolved by 0.23, which adds a url to sources:

typedoc/src/test/converter/alias/specs.json

Lines 22 to 29 in 03d948e

	"sources": [
	{
	"fileName": "alias.ts",
	"line": 14,
	"character": 12,
	"url": "https://github.com/TypeStrong/typedoc/blob/fake/src/test/converter/alias/alias.ts#L14"
	}
	],

That said, I'm not opposed to a baseDir option which controls this, preventing the getCommonDirectory behavior.

[milesj]

@Gerrit0 Will this url be available for the JSON outputs also?

[Gerrit0]

Yes, url is included in the json in 0.23

[milesj]

Awesome, looking forward to it.