Typedoc: Local file path stored in docs

[btgoodwin]

I'm using the following configuration for my project:

{
    "theme": "minimal",
    "module": "commonjs",
    "target": "ES6",
    "readme": "README.md",
    "mode": "file",
    "exclude": "./**/*+(e2e|spec|index).ts",
    "excludePrivate": "true"
}

And I'm running TypeDoc (v0.9.0): typedoc --options typedoc.json --out docs src/lib.

My output documentation results in references to modules in node_modules with the path stored in the documentation itself. In other words, I'll end up with lines like this:

Inherited from <some external name>
Defined in /home/my_user/.../node_modules/<external library>/...

I've tried using the externalPattern set to ./node_modules/**/* and excludeExternal, but it ends up excluding my entire module (i.e., the documentation is just an index file with my readme in it).

What is the correct configuration to prevent references to my local filesystem ending up in my published documentation?

[btgoodwin]

Never mind, I found someone else's response in a different issue thread that indicated using "exclude": "**/node_modules/**" was the way to go. That seems to have resolved it for me (i.e., preventing it from providing my local host's file system paths into the documentation).

[btgoodwin]

Actually, that didn't fix it. On the local copy of the generated docs, whole offending sections of the documentation are no longer visible. Once it was published, all of those sections are now visible and of course have /home/user... embedded into them despite having set "exclude": "**/node_modules/**".

It's still unclear how to prevent it from pulling in those external links.

[sdirix]

We have the same problem. Would be great if this could be fixed at some point. An easy workaround would be to not provide a Defined in path when it can't be resolved properly. The Inherited information is sufficient.

[iliveoncaffiene]

Working on a team project with this issue is a huge annoyance. All node_modules paths are local paths and update every time someone else works on it (3 people working = 3 computers = 3 different paths that it flops between).

[zajrik]

Currently having this issue myself. I can't believe this has been an open issue for 2 years. Any word on this?

[Gerrit0]

Could someone experiencing this provide a repo + doc generation script that reproduces the issue? I have been unable to reproduce this on the TypeDoc repo.

[zajrik]

For me, the issue is presenting itself when I run TypeDoc on a project containing a class that inherits from some class provided by an external library. The "Defined in..." section of all the inherited members on that class display the local file paths to the external library. Specifically, they're pointing to the Error definition in the node lib definitions file in the TypeScript folder within TypeDoc's node_modules itself if I recall correctly. I haven't poked around with it since I left work yesterday.

I was able to work around the issue for the current specific project I'm working on by not extending Error directly and simply manually capturing a stack trace.

But I know I'm also planning on writing another library module in this set of separate modules once I conclude this current module and it will have to explicitly inherit from an external library so this problem will present itself once again.

[zajrik]

I whipped up a quick repo where the issue is definitely occurring.

https://github.com/zajrik/typedoc-test

You can see in docs/classes/testerror.html that any of the "defined in" sections show a path to a local file, for example:

<aside class="tsd-sources">
    <p>Inherited from Error.message</p>
    <ul>
        <li>Defined in D:/Code Stuff/node-projects/sambo/docs-test/node_modules/typedoc/node_modules/typescript/lib/lib.es5.d.ts:974</li>
    </ul>
</aside>

This result can be reproduced with npm run docs or yarn docs if you prefer.

Is there something we're missing to allow us to exclude local file paths in the output? I don't mind having inherited members listed. I just don't want my filesystem information inserted into the documentation. Even if it's not necessarily compromising in any way, I just don't care to see it on there, especially since it provides no useful information for those without any way to actually see the file it points to.

[Gerrit0]

Thanks! This should definitely be fixable, not sure what's causing it yet, but I'll look into it.

[zajrik]

Awesome! Glad I could help. If you need anything else let me know. I'd really like to be able to use TypeDoc in the end for my multi-module project. Using JSDoc on the transpiled JS in my last big project really just isn't cutting it for me anymore. It's too clunky and I had to hack extra features into JSDoc and the theme I'm using just to satisfy how I wanted the documentation to be. TypeDoc provides all of the changes I made to JSDoc with the added benefit of supporting TS out of the box so no extra steps.

[Gerrit0]

Well, that was an... interesting debugging session. Apparently just using require('path').relative to define paths relative to the cwd isn't good enough... and we needed a custom algorithm with labeled for loops so that we can break out of inner loops to figure out the base path. base-path.ts.

Why? I have no idea. The issue is that all the code for a project generally lives under src/ or some such directory, and these are the only files that are passed to add in the above class... calling this.basePath.add(fileName); on line 112 in SourcePlugin.ts at least makes the file names relative to the project directory, but it doesn't feel like the right solution. I'll keep digging.

[Gerrit0]

For anyone who would like to just remove the "Defined in" sections when no url is known (which catches this case), you can create a custom theme with just this change:

1. Create a theme directory
2. Create theme/partials/member.sources.hbs
3. Paste in the code from the original but remove the else block starting on line 16.
4. Tell TypeDoc to use your theme with --theme path/to/your/theme

This isn't a perfect solution, as we probably shouldn't be outputting full paths in the JSON output, but for anyone just using the HTML output, it should work until we come up with the right solution.

[zajrik]

That solution may indeed be decent enough for one of my two plans, which is having each module's documentation link to the other modules while still using TypeDoc to generate the sites. The other plan I had was to write my own documentation site that can load the documentation json from all modules of my project and display the documentation in one place.

I'm less inclined to go with the latter because front-end is not my forte at all. I'd argue it's not worthy of being called a part of my skillset.

I'll definitely be keeping my eye on the progress here.

Thank you again for looking into it.

[Gerrit0]

This has been fixed in 0.15.2, just using the fix I mentioned above. I'm still not convinced it is the best solution, but it is at least consistent with how TypeDoc behaves with other paths.

[zajrik]

Oh cool. I was actually just about to add this to my modified fork of the default themes so this saves me the trouble.

Thank you!

[pluma]

If anyone else is having trouble with this: typedoc seems to infer the relative path based on where it was installed, so installing it globally can result in local file paths being relative to the common base path (typically your home directory).

[Gerrit0]

Another alternative solution - as of 0.17, there is the --disableSources option which will disable the tracking of where a symbol is defined.

[pluma]

Sure but that's more of a workaround than a solution as it will remove the file paths completely. I was trying to figure out why the paths were leaking information about my environment rather than just the code base.

[kuba-orlik]

I can confirm @pluma's suggestion. Installing typedoc locally in the project dir solved the issue