krisztianb/typedoc-plugin-merge-modules

Plugin for TypeDoc that merges the content of modules

typedoc-plugin-merge-modules

This is a plugin for TypeDoc that merges the content of modules.

Use cases:

• If you want to document an entire application and not a library, you can specify all files that you want to have documented as entry points for TypeDoc and use this plugin to merge all modules into the project root removing the extra module layer.
• If you want to merge the content of some modules in the TypeDoc output, you can use this plugin and module annotations in your files to specify which modules should be combined.

Example

Here is an example of how the navigation menu of TypeDoc's output changes when merging all modules into the project root using the plugin:

Installation

This module can be installed using npm:

$ npm install typedoc-plugin-merge-modules --save-dev

The plugin requires TypeDoc version 0.24.x or 0.25.x to be installed. After installation you need to activate the plugin with a typedoc command line argument or inside your typedoc config file.

Here is an example using a JavaScript config file:

/** @type { import('typedoc').TypeDocOptionMap & import('typedoc-plugin-merge-modules').Config } */
module.exports = {
    out: "output",
    entryPointStrategy: "expand",
    entryPoints: ["input/module1.ts", "input/module2.ts"],
    tsconfig: "tsconfig.json",
    readme: "MAIN.md",
    plugin: ["typedoc-plugin-merge-modules"],
    mergeModulesRenameDefaults: true, // NEW option of TypeDoc added by this plugin
    mergeModulesMergeMode: "project", // NEW option of TypeDoc added by this plugin
};

After installation TypeDoc can be used normally and you can configure this plugin as described below.

Options

The following options are added to TypeDoc when the plugin is installed:

Name & Format	Description	Default
mergeModulesRenameDefaults <boolean>	Defines if the plugin should rename default exports to their original name.	true
mergeModulesMergeMode <"project"|"module"|"module-category"|"off">	Defines how the plugin should merge modules: "project" = The plugin merges the content of all modules into the project root. "module" = The plugin merges modules with the same name. By default the filename is the module name, which you can overwrite using module comments. "module-category" = Same as "module" but will only merge modules that have the same category. "off" = Disables the plugin.	"project"

When you set mergeModulesMergeMode to "module" OR "module-category" in combination with module comments you should add the tag @mergeTarget to the comment of the module whose comment should be used in the merge result.

Bugs

Please report bugs here. Thanks for your contribution!

Credits

Special thanks go to the following people that contributed to this project:

• Gerrit Birkeland for the suggested solution and code example.
• Felipe Santos for suggesting improvements.
• Sho Otani for implementing the merging of modules by name.

Donate

If you find this piece of software helpful, please consider a donation. Any amount is greatly appreciated.

typedoc-plugin-merge-modules's Issues

Difficulty using options

I have tried adding "mergeModulesMergeMode": "module" to my typedoc.json file, but now TypeDoc throws error Error: Tried to set an option (mergeModulesMergeMode) that was not declared..

It does load typedoc-plugin-merge-modules right before throwing the error, so I believe I'm at fault for using the option the wrong way. How should I use it, though?

merge things into the same file

Hello, and thanks for updating this plugin to work with the latest TypeDoc!

Now, on to my issue. I was wondering if there could be a new option to merge things on to the same page.

For example, with the following typedoc.json:

{
    "$schema": "https://typedoc.org/schema.json",
    "entryPointStrategy": "Resolve",
    "entryPoints": [
        "./src/foo.ts",
        "./src/bar.ts"
    ]
}

And the following foo.ts:

export enum FooEnum {
  VALUE_1 = 0,
  VALUE_2 = 1,
}

export interface FooInterface {
  thing1: number;
  thing2: number;
}

And the following bar.ts:

// Same as "foo.ts", just different names.

export enum BarEnum {
  VALUE_1 = 0,
  VALUE_2 = 1,
}

export interface BarInterface {
  thing1: number;
  thing2: number;
}

Without any plugins, TypeDoc will generate docs that have FooEnum, FooInterface, BarEnum, and BarInterface all on separate HTML pages.

Instead, what I want is to have 2 HTML pages with 2 things each on them, because I have explicitly told TypeDoc to have 2 entry points.

(Essentially, this would allow people to document "chunks" or "features" of an app/library, and have everything concerning the feature be contained on a single HTML page.)

Is this possible?

@packageDocumentation not behaving correctly

Hello,

I was hoping I am able to specify a module-level documentation block by specifiying the @packageDocumentation annotation as per these docs.
I am currently using your package as a replacement for this obsolete package which provided such a feature.
See here.

Would it be too much work to include this functionality?

Usage with monorepo doesn't seem to work

Hi!
First of all thanks for your plugin :)

We are having issues working with [email protected] and typedoc-plugin-merge-modules in a monorepo.

In the [email protected] release, the author rebuilt the way typedoc works and how it builts the documentation for monorepos.

Currently, we are not able to make typedoc-plugin-merge-modules work in a monorepo with multiple packages

This worked with [email protected] and the previous version of the plugin

Expected Behavior

The documentation generated for all the packages properly merge the different packages with the same @module @mergeTarget tags

Current Behavior

Modules are not merged and are shown independently.

Steps to Reproduce

I will provide a repo with an example, we use Nx for the monorepo.

We have these projects in Nx

each one with his own package.json

[email protected] requires to split the configurations, we created a typedoc.json in both of them

the index.ts (entry point configured for typedoc) has the comments

but the result is

and here the typedoc global config

I will provide an example repository this afternoon :)

Interface and Properties names are not replacing 'default'

Thank you very much for this plugin!
When I run:
npx typedoc --pretty --mergeModulesRenameDefaults true ./src

The plug does fix most of my 'default' naming problems, but it is not working with property names and interface names.

Interface:

export default interface CRUDServiceInterface {

Property... if that is what we'll call it:

function loggerFactory(): winston.Logger {
...
    return logger;
}

export default loggerFactory();

Fixing the interface name would be the most helpful, and straightforward.
As for the 'property', I would recommend either a lowercase of the file name.

• Example: logger

Or, something like: <filename>/@default

• Example: Logger.ts/@default

Error when running typedoc

When running typedoc I'm getting the following error:

The plugin C:**\base\node_modules\typedoc-plugin-merge-modules could not be loaded.
Error: C:**\base\node_modules\marked\src\marked.js:158
const prevRenderer = extensions.renderers?.[ext.name];

Namespaces and Interfaces are not merged.

package.json:

{
  "devDependencies": {
    "typedoc": "0.22.13",
    "typedoc-plugin-markdown": "3.11.14",
    "typedoc-plugin-merge-modules": "3.1.0",
    "typescript": "4.6.3"
  },
  "name": "issue",
  "type": "module"
}

typedoc.json:

{
  "cleanOutputDir": true,
  "entryPointStrategy": "expand",
  "entryPoints": [
    "src"
  ],
  "gitRevision": "master",
  "hideBreadcrumbs": true,
  "hideInPageTOC": true,
  "hideLegend": true,
  "out": "_doc",
  "readme": "none"
}

tsconfig.json:

{
  "compilerOptions": {
    "allowJs": true,
    "declaration": true,
    "emitDeclarationOnly": true
  },
  "include": [
    "src/**/*.js"
  ]
}

src/file.js:

/**
 * Some module.
 *
 * @module
 */

/**
 * This description is not in the documentation!
 *
 * @callback Type1 This description is not in the documentation!
 *
 * @param {number} one This description is not in the documentation!
 * @param {number} two This description is not in the documentation!
 *
 * @returns {number} This description is not in the documentation!
 */

/**
 * @typedef {{(one: number, two: number) => number}} Type2
 *
 * Some type 2.
 */

/**
 * This block will be placed in the `interfaces/Type3.md` file
 * instead of the `README.md` file.
 *
 * @typedef Type3 Some type 3.
 *
 * @property {number} one property #1
 * @property {number} two property #2
 */

/**
 * @typedef {{
 *   one: number;
 *   two: number;
 * }} Type4
 *
 * Some type 4.
 */

/**
 * Some type 5.
 *
 * This block will be placed in the `modules/Type5.md` file
 * instead of the `README.md` file.
 */
export const Type5 = {}

/**
 * @param {number} n
 *
 * @returns {number}
 */
Type5.id = n => n

Type5.answer = 42

After running

npx typedoc

and

ls -R _doc

we got

README.md       interfaces      modules

_doc/interfaces:
Type3.md

_doc/modules:
Type5.md

When the plugin is turned off it still renames default exports

Version 2.1.0 introduced the possibility to turn the plugin off with an option.

The code that renames default exports does not honor that option.

Should this plugin also replace "default" with the field name?

First of all: your plugin saved my life. Thank you so much!

This started at TypeStrong/typedoc#1521. So, now that all modules are merged, I think it does not make sense anymore to use "default" as the fieldname.

So, my point here is: should this plugin also replace "default" with the field name? I'm not asking to do, just discussing :).

Plugin fails to load with typedoc 0.22.3

output:

$ ./node_modules/.bin/typedoc --version
Error: The plugin typedoc-plugin-merge-modules could not be loaded.
Error: Error [ERR_PACKAGE_PATH_NOT_EXPORTED]: Package subpath './dist/lib/converter' is not defined by "exports" in /home/osesov/tizen/vscode/zplayer/node_modules/typedoc/package.json
    at new NodeError (node:internal/errors:371:5)
    at throwExportsNotFound (node:internal/modules/esm/resolve:413:9)
    at packageExportsResolve (node:internal/modules/esm/resolve:652:3)
    at resolveExports (node:internal/modules/cjs/loader:482:36)
    at Function.Module._findPath (node:internal/modules/cjs/loader:522:31)
    at Function.Module._resolveFilename (node:internal/modules/cjs/loader:919:27)
    at Function.Module._load (node:internal/modules/cjs/loader:778:27)
    at Module.require (node:internal/modules/cjs/loader:1005:19)
    at require (node:internal/modules/cjs/helpers:94:18)
    at Object.<anonymous> (/home/osesov/tizen/vscode/zplayer/node_modules/typedoc-plugin-merge-modules/dist/plugin.js:4:21)

TypeDoc 0.22.3
Using TypeScript 4.4.2 from ./node_modules/typescript/lib

If that helps - recently the same situation used to be with typedoc-plugin-markdown #249

merge those module has the same name but in different categories

hi, thx you for this plugin. is there any possible can add an option to prevent merge those same name modules which in different categories?