christopherthielentypedoc-plugin-external-module-name
What
A Typedoc plugin which allows code documentation to be organized into custom Modules.
Note: In Typedoc 0.17.0 and above, Module refers to an ES6 Module. In Typedoc 0.16.x and below, an ES6 Module was called an External Module. Although the plugin's name includes "External Module", it modifies Modules (ES6 Modules)
By default, Typedoc creates a Module for each ES6 Module (each file).
This plugin allows documentation to be moved to arbitrary modules. It also supports merging multiple modules into a single module. By default, all Modules in a given directory will be merged into a single module.
Suppose your source files are organized like this:
thing1/foo.ts
thing1/bar.ts
thing2/baz.ts
thing2/qux.tsBy default, Typedoc would create four Modules:
thing1/foo: containsfoodocumentationthing1/bar: containsbardocumentationthing2/baz: containsbazdocumentationthing2/qux: containsquxdocumentation
With this plugin, Typedoc creates two Modules:
thing1: containsfooandbardocumentationthing2: containsbazandquxdocumentation
Installing
Typedoc has the ability to discover and load typedoc plugins found in node_modules. Simply install the package usng your package manager and run typedoc.
npm install -D typedoc-plugin-external-module-name
typedocUsing
Directory Based
This plugin will combine documentation from the files in each given directory into a new Module. The new module name is generated from the directory's location in the source tree.
Explicit via Annotation
You can explicitly specify a Module name using the @module annotation.
Add a comment block at the top of a Typescript file with @module modulename.
Mark the comment block as @packageDocumentation to let typedoc know that this is documentation for the file (Module) itself
(see: Typedoc Docs).
/**
* @packageDocumentation
* @module module1
*/Top level module comments
When multiple modules are merged, the merged module summary is chosen arbitrarily from the first file processed.
To use a specific file's comment block as the Module page summary, use @preferred.
/**
* This comment will be used as the summary for the "thing2" module.
* @packageDocumentation
* @module thing2
* @preferred
*/Custom Module Name Generation
Create a file named .typedoc-plugin-external-module-name.js in the folder you launch typedoc from.
Create a custom mapping function in that file and export it using CommonJS.
For each Module, the plugin will call your function and use the return value as the Module Name.
module.exports = function customMappingFunction() {
return "custom" // everything goes into "custom"
}The Function should have the following signature:
type CustomModuleNameMappingFn = (
explicitModuleAnnotation: string,
implicitFromDirectory: string,
path: string,
reflection: Reflection,
context: Context,
) => string;The arguments are:
moduleAnnotation: If the module has an explicit annotation, i.e.,@module explicitimplicitFromDirectory: The plugin's default mappingpath: The path to the filereflection: The ModuleContainerReflectioncontext: The typedocContext
Example:
const subpackage = new RegExp("packages/([^/]+)/");
module.exports = function customMappingFunction(explicit, implicit, path, reflection, context) {
// extract the monorepo package from the path
const package = subpackage.match(path)[1];
// build the module name
return `${package}/${implicit}`;
}