Support for library mode

[Gerrit0]

This turned out to be far simpler to implement than I expected, despite the crazy large diff (mostly spec updates)

📦 Changes

1. Added --mode library
2. Moved TypeScript to a peer dependency
3. Renamed modules to namespaces and external modules to modules

🚀 Try it out

The changes in this PR have been published as typedoc@next. You can install it and try it out with:

npm install typedoc@next typescript
npx typedoc --mode library --out docs src/index.ts

📚 Library Mode

This is the flagship feature for 0.170.18. With this mode, TypeDoc will take each of the specified input files and generate documentation for that input file as one module. It will resolve any re-exports of that module and treat them as if they were declared in that file. Note that if you have multiple entry points that export the same symbol from a helper file, this will result in multiple copies of that symbol in your documentation

Note that input files are still expanded before conversion. If you specify a directory, every file in that directory and subdirectories will be treated as a library entry point.

🔓 TypeScript Peer Dependency (shipped in 0.17)

TypeDoc has kept TypeScript as a dependency for a long time. The cited reason for this is that the project uses internal compiler APIs that any new version of TypeScript could break.

However, in practice, the internal APIs that TypeDoc uses have remained stable since I first started working on the project over a year ago. In addition to this, many TypeDoc users hacked around TypeDoc's strict version limitations by removing TypeScript from TypeDoc's node_modules folder.

TypeDoc still uses internal APIs. I expect it will break with some future version of TypeScript, but giving users the ability to use a newer TS version is a good thing. For now, the peer dependency will require at least the minor version of TypeScript kept in TypeDoc's dev dependencies.

➡️ Renamed External Modules (shipped in 0.17)

"External Modules" have been renamed to be properly called "Modules", and the legacy "Modules" have been renamed to "Namespaces". This is a major breaking change for plugins and themes with custom CSS, but has been overdue for a long time.

❓ Unresolved Questions

• For library mode, if there is only one entry point, should the module be removed and all reflections be present in the root reflection? (This would look like --mode file but with exports from the entry point only)
• The way library mode works makes it behave as if --excludeNotExported was set, does this make sense? I think it does... Should library mode remove the only exported checkbox in the generated docs?

Closes #109
Closes #639
Closes #880

[socsieng]

Update help text?

[socsieng]

Should also probably update readme file as well:

--mode <file|modules>

[Gerrit0]

Good catch, thanks!

[Gerrit0]

Website docs will also be updated by TypeStrong/typedoc-site#26

[danmarshall]

Hi @Gerrit0 , I very much appreciate this work 🥇 I have been wanting this capability for a long time.
I am trying it out but I do not get any output at all, other than blank pages for global and my index module.

My minimal sample repo is https://github.com/danmarshall/test-typedoc-library and I have generated the docs here: https://danmarshall.github.io/test-typedoc-library/
Thanks!

[rolftimmermans]

Love this, thanks for your work!

Is re-exporting already supposed to work? I'm trying this:

internal.ts

/**
 * Re-exported function.
 **/
export function foo() {

}

index.ts

export {foo} from "./internal"

/**
 * Exported function.
 **/
export function bar() {

}

When running yarn run typedoc --mode library index.ts I only see the bar() function documented. I would expect both bar() and foo() to be visible in the final documentation, under the "index" export.

Tested with version 0.17.0-1.

[Gerrit0]

Oops! Sorry about that @danmarshall and @rolftimmermans. Both of those should have worked. I forgot to resolve symbol aliases before trying to document the node.

Will be fixed in 0.17.0-2 shortly.

[rolftimmermans]

Perfect! The re-exports now work very well.

The only downside I see at the moment is that the entry points are a bit hard to find. For libraries with a single (main) entry point it would be good to just be able to treat all symbols as "globals", so that they are visible immediately in the table of contents when opening the main/readme page.

See the screenshot: all API documentation is "hidden" behind the unfortunately named "index" link.

The ToC in this screenshot (generated with @gnd/typedoc) might be nicer for a lot of libraries, because the symbols are easily accessible and it is obvious where to look:

[Gerrit0]

I guess there's a couple votes for not creating a module if only one entry point is provided. I think it should be relatively simple to do.

[Weakky]

Hey, thanks for your amazing work 🙏. I tried running the library mode against https://github.com/prisma-labs/graphql-santa, but ran into an issue. We are exposing ts types from some underlying external libraries.

Is there any way to get the type information from them? I tried adding --includeDeclarations, but that doesn't seem to work
Instead, most the the type informations contain just the name of the types, but are not "clickable"/discoverable

[danmarshall]

@Weakky - I have a similar scenario. It does make me wonder how far the crawling should go. All the way to the base TypeScript libs?

[TheNeuralBit]

This is awesome, thanks so much @Gerrit0. I tried this 0.17.0-2 out on the arrow docs and it looks great!

FYI @trxcllnt and @lmeyerov I pushed up a preview. gh-pages doesn't seem to work right but you can browse it with githack.com: https://raw.githack.com/TheNeuralBit/arrow/typedoc-library/js/doc/index.html

[Weakky]

@danmarshall Yeah, that makes sense to me, unless specified otherwise with a flag. I see two ways to filter out deps:

• Either by depth
• Or by a list of include (or exclude)

There is already a mechanism to parse types from node_modules, but it looks like the new library mode isn't taking that into account

[eritbh]

Thanks so much for working on this! I'm running into an error when trying to run this on my project, any help? I'm working with this repository on WSL.

Console session output

george ~/yuuko $ yarn run typedoc --version
yarn run v1.21.1
$ /home/george/yuuko/node_modules/.bin/typedoc --version

TypeDoc 0.17.0-2
Using TypeScript 3.7.5 from /home/george/yuuko/node_modules/typescript/lib
Done in 0.68s.
george ~/yuuko $ yarn run typedoc --mode library --json test.json src/Yuuko.ts 
yarn run v1.21.1
$ /home/george/yuuko/node_modules/.bin/typedoc --mode library --json test.json src/Yuuko.ts

Using TypeScript 3.7.5 from /home/george/yuuko/node_modules/typescript/lib
/home/george/yuuko/node_modules/typedoc/dist/lib/converter/nodes/block.js:84
            for (const declaration of resolved.declarations) {
                                               ^

TypeError: resolved.declarations is not iterable
    at BlockConverter.convertVisibleDeclarations (/home/george/yuuko/node_modules/typedoc/dist/lib/converter/nodes/block.js:84:48)
    at /home/george/yuuko/node_modules/typedoc/dist/lib/converter/nodes/block.js:50:26
    at Context.withScope (/home/george/yuuko/node_modules/typedoc/dist/lib/converter/context.js:101:9)
    at /home/george/yuuko/node_modules/typedoc/dist/lib/converter/nodes/block.js:49:25
    at Context.withSourceFile (/home/george/yuuko/node_modules/typedoc/dist/lib/converter/context.js:85:9)
    at BlockConverter.convertSourceFile (/home/george/yuuko/node_modules/typedoc/dist/lib/converter/nodes/block.js:39:17)
    at BlockConverter.convert (/home/george/yuuko/node_modules/typedoc/dist/lib/converter/nodes/block.js:30:18)
    at Converter.convertNode (/home/george/yuuko/node_modules/typedoc/dist/lib/converter/converter.js:116:53)
    at Converter.compile (/home/george/yuuko/node_modules/typedoc/dist/lib/converter/converter.js:159:26)
    at Converter.convert (/home/george/yuuko/node_modules/typedoc/dist/lib/converter/converter.js:90:29)
error Command failed with exit code 1.
info Visit https://yarnpkg.com/en/docs/cli/run for documentation about this command.

Regarding the questions posed in the OP:

For library mode, if there is only one entry point, should the module be removed and all reflections be present in the root reflection?

This would be my use case, +1.

The way library mode works makes it behave as if --excludeNotExported was set, does this make sense? I think it does...

I think this makes sense, but I wouldn't be against requiring both flags for this behavior either in case someone has a valid use case for not inferring --excludeNotExported.

Should library mode remove the only exported checkbox in the generated docs?

This behavior should probably be separated from library mode and be implemented as part of --excludeNotExported if it's not already present. If it's decided that library mode will imply that flag as well, then the checkbox should go away. (Is the checkbox not already hidden from the docs when using that flag? If not, this is probably a question for a separate PR entirely.)

[suchipi]

Hello! I am really excited for this feature. I pulled next and tried it out, but found that some of the stuff in my package was not documented; specifically, functions that were inside objects, like follows:

import Foo from "./Foo";
import Bar from "./Bar";

export default { Foo, Bar };

I have created a repro repo for this here: https://github.com/suchipi/typedoc-object-repro

[aciccarello]

This looks great! Glad to see library mode added. What do you think about making this a 1.0 release?

[telamonian]

@Gerrit0 Just to let you know, jupyterlab has pinned to 0.17.0-3 and is still using library mode for our API docs. And they are spectacular (or at least much better than they were previously). Thanks for all the great work on this so far!

[codycuellar]

I just want to +1 this effort. It's the only mode that makes any sense to me. There's still a few minor issues - but overall it documents things in a way that is clear for consumers of our library, AND for devs of the library, and doesn't really require any extra plugins and doc tags to get it working as expected.

[Gerrit0]

Thanks for the feedback! I'm glad it has been useful.

I just realized today that typedoc.org has been pointing people to this PR, which won't be merged. There is a beta up for TypeDoc 0.20 which acts as described in this PR (the mode option was removed, so I can't really call it library mode) See #1364 for updates on that.