Typedoc: Document only a library's exported files from a given starting point

[manrajgrover]

Currently, typedoc exports all internally exported entities which are not part of the exports in the given starting point. I've been trying to find a way to get past that using available options but looks like this feature is not available.

For example, if starting point is src/index.ts, then only exports from this file should be documented and not all entities. Restricting files in config file or marking every internal utility function as @hidden makes things unmaintainable.

If I have missed anything, please let me know.

[manrajgrover]

@aciccarello Any updates on this?

[aciccarello]

@ManrajGrover No movement yet. I like the idea though. Currently the "interval" vs "external" concepts are pretty limited and probably need to be thought through. There is a community made plugin to override these via doc tags if you are interested but it may not fit the bill of what you are looking for.

PRs are welcome :heart:

[manrajgrover]

@aciccarello Thanks for the update. I'm pretty new to TypeScript Compiler API and although I tried going through their examples, I found their documentation lacking in this regard. I would appreciate if you could share more information/pointers on the same.

[aciccarello]

@ManrajGrover I didn't write TypeDoc so I don't have much experience with the compiler API. I can tell you that TypeDoc uses some internal TypeScript apis that aren't included in the public api.

[aciccarello]

I'm thinking this would be a new mode (maybe named "library"). I not sure how to handle projects with multiple entry points (e.g. rxjs/Observable vs rxjs/Subject). Ideas are welcome.

[FranklinYu]

Should the new "library" mode ignore everything in node_modules?

[aciccarello]

@franklinyu I don't think that should be conflated with a "library" mode. A library may want to include types for an imported module. Excluding node_modules can be discussed further in #319.

[Gerrit0]

I not sure how to handle projects with multiple entry points (e.g. rxjs/Observable vs rxjs/Subject)

I think this should be handled in basically the same way as we already handle accepting files. typedoc --mode library rxjs/Observable.ts rxjs/Subject.ts

[FranklinYu]

What if

typedoc --mode library rxjs/*.ts

? Regard all those TypeScript sources as entry points?

[Gerrit0]

Yes, the expandInputFiles method on the Application class will already do this.

[yordis]

@Gerrit0 I tried to implement this but I got nowhere.

I tried to find where in the source code I would filter what gets generated in the documentation as @hidden do it.

Could you give me some ideas of the source code so I could try to fix this? Too much code right now so any extra help will be appreciated.

[Gerrit0]

I think the best place to filter would probably be when first generating reflections, so no reflection would be generated if it doesn't come from an input file...

It seems like the place to do this would be createDeclaration, since other filters (excludeNotExported) are applied there.

I'm not sure it's the best place, but it seems to be the right place for now.

[yordis]

Alright around here https://github.com/TypeStrong/typedoc/blob/a2fab7cf1b5957c2e05ffd3882583dcf812ea8c7/src/lib/converter/factories/declaration.ts#L53

I want to exit if the reflection is not being exported and the reflection is an actual module export.

I am having a little bit of trouble understanding https://github.com/TypeStrong/typedoc/blob/1c4c5151cec938ef03cae79c33c12be8d587ea74/src/lib/models/reflections/abstract.ts#L32-L66 types and what they actually mean.

And these https://github.com/TypeStrong/typedoc/blob/1c4c5151cec938ef03cae79c33c12be8d587ea74/src/lib/models/reflections/abstract.ts#L68-L84

I see some keys like these https://github.com/TypeStrong/typedoc/blob/1c4c5151cec938ef03cae79c33c12be8d587ea74/src/lib/models/reflections/abstract.ts#L74-L75 but I am not quite sure what they are.

Right now I need to figure out which types are useful.

I don't care if the thing is a variable declaration, function, or whatever, as long as it is actually being exported.

I tried to use https://github.com/TypeStrong/typedoc/blob/1c4c5151cec938ef03cae79c33c12be8d587ea74/src/lib/models/reflections/abstract.ts#L140

But even interface keys will be true it wouldn't work to use the key by itself since the filtering is for things being directly exported on the module.

Sorry for the confusion, I am trying to put the pieces together.

[Gerrit0]

Yea, that isExported on the reflections class won't be helpful since you are trying to determine exports from the entry point.

I think the way to do this is to get the module symbol from the entry point, and then see if a given node's symbol is in the exported map of that module. You'll need to access TS apis as this knowledge isn't included in the typedoc reflections yet.

[yordis]

@Gerrit0 any extra directions in terms of file and where to start looking for this will be helpful. I will give another try to this so I can find that information from the TS.

[shrinktofit]

https://github.com/shrinktofit/typedoc/commit/ab2f239c8e9710445228effada2640c863ece997
Please take a look at this commit in my fork reposity.
It support:

export * from "xx";
export { A, B as C } from "yy";

import * as D from "zz";
export { D };

If your project is made as a single library so that it can be imported by user from a root index.ts(or a bundle packed by packing-tools), the result will exactly contain the entities that your index.ts exported.
At this point, only one external module exists. (If you call typedoc with only one input file).

[eritbh]

Any movement on this? If that code works, can it be PR'd? I'm itching to use this to document a library I'm writing.

[capraynor]

shrinktofit@ab2f239
Please take a look at this commit in my fork reposity.
It support:

export * from "xx";
export { A, B as C } from "yy";

import * as D from "zz";
export { D };

If your project is made as a single library so that it can be imported by user from a root index.ts(or a bundle packed by packing-tools), the result will exactly contain the entities that your index.ts exported.
At this point, only one external module exists. (If you call typedoc with only one input file).

Man this commit is so cool. Solved my problem.

[FranklinYu]

@shrinktofit Ready for PR? I think this should be the solution.

[englercj]

The referenced commit no longer seems to be available, is there a different workaround for documenting node modules that only export a subset of the objects in the modules?

Would love to specify only my index.ts file and let typedoc crawl the exports.

[eritbh]

Still available for me, https://github.com/shrinktofit/typedoc/tree/leslie

It appears I'm able to create a pull request from another user's fork, but I feel like that's in poor taste. Would rather @shrinktofit push this forward themselves.

[shrinktofit]

Sorry for being late. The PR is available now.

[satouriko]

shrinktofit@ab2f239
Please take a look at this commit in my fork reposity.
It support:

export * from "xx";
export { A, B as C } from "yy";

import * as D from "zz";
export { D };

If your project is made as a single library so that it can be imported by user from a root index.ts(or a bundle packed by packing-tools), the result will exactly contain the entities that your index.ts exported.
At this point, only one external module exists. (If you call typedoc with only one input file).

Is there any way to omit the index / index.d? That feels bad.

[Gerrit0]

With the work done for export declarations, I think it is almost possible to finally do this, once one of the implementations is merged, I'll give developing a library mode a shot.

[Gerrit0]

So it turns out that actually implementing library mode was way easier than I anticipated.

If you wanted this feature, please check out #1184. There is a beta release out with the functionality, but I'd like to iron out any kinks before merging to master.

[y-nk]

@Gerrit0 this still an open issue, right? library mode isn't there anymore and even for mode file, typedoc is scanning through every variable/function/type declared on a file level, exported or not. Is there a way to reuse the code from this PR and add a flag --onlyExported ?

[Gerrit0]

Yes, this is still an open issue. It is being worked, but due to issues discovered with the initial implementation, has grown considerably larger than expected. https://github.com/TypeStrong/typedoc/pull/1184#issuecomment-650809143 is the latest update on it.

[y-nk]

@Gerrit0 thank you for the update. my knowledge of the project is still very limited but let me know if i can be of help.

[Gerrit0]

Of all the issues for me to miss updating on release...

0.20 has been released, which behaves as described in this issue.