feat(doc-tools): add typedoc plugin (#4174)

* feat: add typedoc plugin

* feat: optimzize the file structure

.changeset/early-ladybugs-search.md

@@ -0,0 +1,7 @@
+---
+'@modern-js/doc-plugin-typedoc': patch
+---
+
+feat(doc-core): add typedoc plugin
+
+feat(doc-core): 增加 typedoc 插件

packages/cli/doc-core/src/shared/types/Plugin.ts

@@ -1,4 +1,4 @@
-import { BuilderConfig } from '@modern-js/builder-rspack-provider';
+import type { BuilderConfig } from '@modern-js/builder-rspack-provider';
 import type { PluggableList } from 'unified';
 import { DocConfig, PageIndexInfo, RouteMeta } from '.';
 

packages/cli/doc-core/src/theme-default/components/Search/logic/util.test.ts

@@ -1,5 +1,6 @@
 import { expect, test, describe } from 'vitest';
 import { backTrackHeaders } from './util';
+import { Header } from '@/shared/types';
 
 describe('utils logic', () => {
   test('back track the headers', () => {
@@ -10,7 +11,7 @@ describe('utils logic', () => {
       { depth: 4, text: '4', id: '4' },
       { depth: 5, text: '5', id: '5' },
     ];
-    const res = backTrackHeaders(headers, 3);
+    const res = backTrackHeaders(headers as Header[], 3);
     expect(res).toEqual([
       { depth: 2, text: '2', id: '2' },
       { depth: 3, text: '3', id: '3' },

packages/cli/doc-plugin-typedoc/.eslintrc.cjs

@@ -0,0 +1,8 @@
+module.exports = {
+  root: true,
+  extends: ['@modern-js'],
+  ignorePatterns: ['index.d.ts'],
+  rules: {
+    '@typescript-eslint/no-non-null-assertion': 'off',
+  },
+};

packages/cli/doc-plugin-typedoc/.gitignore

@@ -0,0 +1,41 @@
+.DS_Store
+
+.pnp
+.pnp.js
+.env.local
+.env.*.local
+.history
+.rts*
+*.log*
+*.pid
+*.pid.*
+*.report
+*.lcov
+lib-cov
+
+node_modules/
+.npm
+.lock-wscript
+.yarn-integrity
+.node_repl_history
+.nyc_output
+*.tsbuildinfo
+.eslintcache
+.sonarlint
+
+dist/
+coverage/
+release/
+output/
+output_resource/
+
+.vscode/**/*
+!.vscode/settings.json
+!.vscode/extensions.json
+.idea/
+
+**/*/typings/auto-generated
+
+.changeset/pre.json
+
+.pnpm-store/

packages/cli/doc-plugin-typedoc/.npmignore

@@ -0,0 +1,37 @@
+.DS_Store
+
+.pnp
+.pnp.js
+.env.local
+.env.*.local
+.history
+.rts*
+*.log*
+*.pid
+*.pid.*
+*.report
+*.lcov
+lib-cov
+
+node_modules/
+.npm
+.lock-wscript
+.yarn-integrity
+.node_repl_history
+.nyc_output
+*.tsbuildinfo
+.eslintcache
+.sonarlint
+
+coverage/
+release/
+output/
+output_resource/
+tests/
+
+.vscode/**/*
+!.vscode/settings.json
+!.vscode/extensions.json
+.idea/
+
+**/*/api/typings/auto-generated

packages/cli/doc-plugin-typedoc/.npmrc

@@ -0,0 +1 @@
+strict-peer-dependencies=false

packages/cli/doc-plugin-typedoc/.prettierrc

@@ -0,0 +1,5 @@
+{
+  "singleQuote": true,
+  "trailingComma": "all",
+  "arrowParens": "avoid"
+}

packages/cli/doc-plugin-typedoc/CHANGELOG.md

@@ -0,0 +1 @@
+# @modern-js/doc-plugin-typedoc

packages/cli/doc-plugin-typedoc/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2021 Modern.js
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

packages/cli/doc-plugin-typedoc/README.md

@@ -0,0 +1,3 @@
+# @modern-js/doc-plugin-typedoc
+
+This plugin is used to generate document by [TypeDoc](https://typedoc.org/) in Modern.js Doc.

packages/cli/doc-plugin-typedoc/modern.config.ts

@@ -0,0 +1,12 @@
+// https://modernjs.dev/module-tools/en/api
+// TODO: Add `defineConfig` after @modern-js/module-tools restore the function
+export default {
+  testing: {
+    transformer: 'ts-jest',
+  },
+  buildConfig: {
+    buildType: 'bundle',
+    format: 'cjs',
+    sourceMap: true,
+  },
+};

packages/cli/doc-plugin-typedoc/package.json

@@ -0,0 +1,76 @@
+{
+  "name": "@modern-js/doc-plugin-typedoc",
+  "version": "2.25.2",
+  "description": "The Documentation Framework of Modern.js.",
+  "homepage": "https://modernjs.dev/doc-tools/",
+  "bugs": "https://github.com/web-infra-dev/modern.js/issues",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/web-infra-dev/modern.js",
+    "directory": "packages/cli/doc-plugin-typedoc"
+  },
+  "license": "MIT",
+  "jsnext:source": "./src/index.ts",
+  "types": "./dist/index.d.ts",
+  "main": "./dist/index.js",
+  "module": "./dist/node/index.js",
+  "scripts": {
+    "dev": "modern-lib dev",
+    "build": "modern-lib build",
+    "reset": "rimraf ./**/node_modules",
+    "lint": "modern-lib lint",
+    "change": "modern-lib change",
+    "bump": "modern-lib bump",
+    "pre": "modern-lib pre",
+    "change-status": "modern-lib change-status",
+    "gen-release-note": "modern-lib gen-release-note",
+    "release": "modern-lib release",
+    "new": "modern-lib new",
+    "test": "vitest run --passWithNoTests",
+    "upgrade": "modern-lib upgrade"
+  },
+  "engines": {
+    "node": ">=14.17.6"
+  },
+  "eslintIgnore": [
+    "node_modules/",
+    "dist/"
+  ],
+  "peerDependencies": {
+    "@modern-js/doc-tools": "workspace:^2.25.2",
+    "react": ">=17"
+  },
+  "devDependencies": {
+    "@modern-js/module-tools": "workspace:*",
+    "@modern-js/doc-core": "workspace:*",
+    "@modern-js/tsconfig": "workspace:*",
+    "@scripts/build": "workspace:*",
+    "@types/node": "^18.11.17",
+    "@types/react": "^18",
+    "@types/react-dom": "^18",
+    "husky": "^8",
+    "lint-staged": "~13.1.0",
+    "prettier": "^2.6.2",
+    "typescript": "^5",
+    "vitest": "0.21.1"
+  },
+  "sideEffects": [
+    "*.css",
+    "*.less",
+    "*.sass",
+    "*.scss"
+  ],
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true,
+    "registry": "https://registry.npmjs.org/"
+  },
+  "dependencies": {
+    "@modern-js/utils": "workspace:*",
+    "typedoc": "0.23.24",
+    "typedoc-plugin-markdown": "3.14.0"
+  }
+}

packages/cli/doc-plugin-typedoc/src/.eslintrc.cjs

@@ -0,0 +1,9 @@
+// eslint-disable-next-line import/no-commonjs
+module.exports = {
+  root: true,
+  extends: ['@modern-js-app'],
+  parserOptions: {
+    tsconfigRootDir: __dirname,
+    project: ['../tsconfig.json'],
+  },
+};

packages/cli/doc-plugin-typedoc/src/constants.ts

@@ -0,0 +1,2 @@
+export const API_DIR = 'api';
+export const ROUTE_PREFIX = `/${API_DIR}`;

packages/cli/doc-plugin-typedoc/src/index.ts

@@ -0,0 +1,83 @@
+import path from 'path';
+import { Application, TSConfigReader } from 'typedoc';
+import { API_DIR } from './constants';
+import { resolveSidebar } from './sidebar';
+
+export interface PluginTypeDocOptions {
+  /**
+   * The entry points of modules.
+   * @default []
+   */
+  entryPoints: string[];
+  /**
+   * The output directory.
+   * @default 'api'
+   */
+  outDir?: string;
+}
+
+export function pluginTypeDoc(options: PluginTypeDocOptions) {
+  let docRoot: string | undefined;
+  const { entryPoints = [], outDir = API_DIR } = options;
+  return {
+    name: 'doc-plugin-typedoc',
+    async addPages() {
+      return [
+        {
+          routePath: `${outDir.replace(/\/$/, '')}/`,
+          filepath: path.join(docRoot!, outDir, 'README.md'),
+        },
+      ];
+    },
+    // The module tools will build error when use the types of doc-core
+    // So we use any type here
+    async config(config: any) {
+      const app = new Application();
+      docRoot = config.root;
+
+      app.options.addReader(new TSConfigReader());
+      console.log('entryPoints', entryPoints);
+      app.bootstrap({
+        name: config.title,
+        entryPoints,
+        plugin: ['typedoc-plugin-markdown'],
+        theme: 'markdown',
+        disableSources: true,
+        readme: 'none',
+        githubPages: false,
+        // @ts-expect-error hide bread crumbs and members symbol
+        hideBreadcrumbs: true,
+        hideMembersSymbol: true,
+        allReflectionsHaveOwnDocument: true,
+      });
+
+      const project = app.convert();
+      if (project) {
+        // 1. Generate module doc by typedoc
+        const absoluteOutputdir = path.join(docRoot!, outDir);
+        await app.generateDocs(project, absoluteOutputdir);
+        const jsonDir = path.join(absoluteOutputdir, 'documentation.json');
+        await app.generateJson(project, jsonDir);
+        // 2. Generate sidebar
+        config.themeConfig = config.themeConfig || {};
+        config.themeConfig.nav = config.themeConfig.nav || [];
+        const apiIndexLink = `/${outDir.replace(/(^\/)|(\/$)/, '')}/`;
+        config.themeConfig.nav.push({
+          text: 'API',
+          link: apiIndexLink,
+        });
+        config.themeConfig.sidebar = config.themeConfig.sidebar || {};
+        config.themeConfig.sidebar[apiIndexLink] = await resolveSidebar(
+          jsonDir,
+        );
+        config.themeConfig.sidebar[apiIndexLink].unshift({
+          text: 'Overview',
+          link: `${apiIndexLink}README`,
+        });
+      }
+      config.route = config.route || {};
+      config.route.exclude = config.route.exclude || [];
+      return config;
+    },
+  };
+}

packages/cli/doc-plugin-typedoc/src/modern-app-env.d.ts

@@ -0,0 +1,2 @@
+/// <reference types='@modern-js/module-tools/types' />
+/// <reference types='@modern-js/plugin-testing/types' />