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 ❤️

[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

typedoc/src/lib/converter/factories/declaration.ts

Line 53 in a2fab7c

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

typedoc/src/lib/models/reflections/abstract.ts

Lines 32 to 66 in 1c4c515

	/**
	* Defines the available reflection kinds.
	*/
	export enum ReflectionKind {
	Global = 0,
	ExternalModule = 1,
	Module = 2,
	Enum = 4,
	EnumMember = 16,
	Variable = 32,
	Function = 64,
	Class = 128,
	Interface = 256,
	Constructor = 512,
	Property = 1024,
	Method = 2048,
	CallSignature = 4096,
	IndexSignature = 8192,
	ConstructorSignature = 16384,
	Parameter = 32768,
	TypeLiteral = 65536,
	TypeParameter = 131072,
	Accessor = 262144,
	GetSignature = 524288,
	SetSignature = 1048576,
	ObjectLiteral = 2097152,
	TypeAlias = 4194304,
	Event = 8388608,
	ClassOrInterface = Class | Interface,
	VariableOrProperty = Variable | Property,
	FunctionOrMethod = ReflectionKind.Function | Method,
	SomeSignature = CallSignature | IndexSignature | ConstructorSignature | GetSignature | SetSignature,
	SomeModule = Module | ExternalModule
	}

types and what they actually mean.

And these

typedoc/src/lib/models/reflections/abstract.ts

Lines 68 to 84 in 1c4c515

	export enum ReflectionFlag {
	None = 0,
	Private = 1,
	Protected = 2,
	Public = 4,
	Static = 8,
	Exported = 16,
	ExportAssignment = 32,
	External = 64,
	Optional = 128,
	DefaultValue = 256,
	Rest = 512,
	ConstructorProperty = 1024,
	Abstract = 2048,
	Const = 4096,
	Let = 8192
	}

I see some keys like these

typedoc/src/lib/models/reflections/abstract.ts

Lines 74 to 75 in 1c4c515

	Exported = 16,
	ExportAssignment = 32,

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

typedoc/src/lib/models/reflections/abstract.ts

Line 140 in 1c4c515

get isExported(): boolean {

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).

[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. #1184 (comment) 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.

[sporritt]

@Gerrit0 I know this issue is closed but I can't figure out whether "library mode" can generate output like that shown by @shrinktofit above:

specifically the concept of multiple modules. I have a base directory with a bunch of modules:

i can library mode on each of these directories individually, for instance:

npx typedoc --mode library --out docs/core ./ts/core

but then i don't have any link between the modules. I'd like to run

npx typedoc --mode library --out docs/core ./ts

but then i just get everything in one.

[sporritt]

...well in fact i'm not using library mode it turns out, as I'm only on 0.16.11. I can't upgrade to 0.20 though because it needs typescript 4, and the shift to declaring it as a peer dependency means it won't install its own version as 0.16.11 did. But that's another matter.

Still would be interested to hear if in 0.20 I should be able to point at the ts directory shown above and get one module for each of the directories in there.

[Gerrit0]

Yes, with 0.20+ you can do that and more. 0.16.11 must have a bug where invalid options don't produce errors... that should be producing an error. 0.20.37 supports TypeScript 3.9 if I recall correctly, so you might still be able to upgrade. 3.9 support wasn't dropped until 0.21.

The command won't be exactly what you specified (unless each folder has only a single index.ts file), however.

npx typedoc --out docs/core ./ts/browser-ui/index.ts ./ts/connector-bezier/index.ts ./ts/connector-flowchart/index.ts ./ts/core/index.ts ./ts/util/index.ts

... at this point, I'd probably switch to a config file.

[sporritt]

Thanks for the reply - much appreciated.