From ee73e9c6293c09f01b4a22f2193edc0de05a32e2 Mon Sep 17 00:00:00 2001 From: Plumbiu <3434909403@qq.com> Date: Sat, 12 Aug 2023 10:44:27 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=F0=9F=93=9A=20=E5=AE=8C=E5=96=84?= =?UTF-8?q?=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/.vitepress/config.ts | 7 ++- docs/about/feature.md | 3 + docs/{principle => about}/how.md | 31 ++++++++-- docs/{principle => about}/optimize.md | 0 docs/guide/full.md | 82 ++++++++++++++++++++------- docs/guide/index.md | 34 ++++++++--- docs/index.md | 2 +- 7 files changed, 123 insertions(+), 36 deletions(-) create mode 100644 docs/about/feature.md rename docs/{principle => about}/how.md (77%) rename docs/{principle => about}/optimize.md (100%) diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts index c53e642e..134fe1b7 100644 --- a/docs/.vitepress/config.ts +++ b/docs/.vitepress/config.ts @@ -8,7 +8,7 @@ export default defineConfig({ // https://vitepress.dev/reference/default-theme-config nav: [ { text: '首页', link: '/' }, - { text: '指南', link: '/guide' }, + { text: '快速开始', link: '/guide/index.md' }, ], sidebar: [ @@ -24,8 +24,9 @@ export default defineConfig({ { text: '关于 truth-cli', items: [ - { text: '原理介绍', link: '/principle/how.md' }, - { text: '优化', link: '/principle/optimize.md' }, + { text: '原理介绍', link: '/about/how.md' }, + { text: '优化', link: '/about/optimize.md' }, + { text: '新特性', link: '/about/feature.md' }, ], collapsed: false, }, diff --git a/docs/about/feature.md b/docs/about/feature.md new file mode 100644 index 00000000..20888da9 --- /dev/null +++ b/docs/about/feature.md @@ -0,0 +1,3 @@ +# 新的特性 + +进入 `truth-cli` 的 [issue](https://github.com/truthRestorer/truth-cli/issues/new/choose) 页面，选择 `Feature request` 选项，我们期望您有兴趣参加 `truth-cli` 的建设。 \ No newline at end of file diff --git a/docs/principle/how.md b/docs/about/how.md similarity index 77% rename from docs/principle/how.md rename to docs/about/how.md index 81fffc1b..2afe33d9 100644 --- a/docs/principle/how.md +++ b/docs/about/how.md @@ -27,7 +27,7 @@ `graph` 的生成很简单，我们只需要通过 `relations` 获取到根目录引用关系，将其添加到对应数据格式的节点中即可。 -需要额外说明的是：`echarts` 中的 graph 图的 node 节点名字是唯一的，所以我们定义好了一个 `Set` 数据结构，如果我们已经添加过这个节点了，那么就不重复添加了 +需要额外说明的是：`echarts` 中的 graph 图的 node 节点名字是唯一的，所以我们定义好了一个 `Set` 数据结构，如果我们已经添加过这个节点了，那么就不重复添加了。 ### tree 图 @@ -37,7 +37,7 @@ 2. `truth-cli` 对应的文件：[@truth-cli/core - genTree](https://github.com/truthRestorer/truth-cli/blob/main/packages/core/src/tree.ts)； ::: -`tree` 数据的生成采用了递归的方式，我们首先通过 `relations` 中的获取项目名，并将其引用的依赖作为当前节点的 `children`，在遍历 `children` 中的所有节点，将节点的引用的依赖作为该节点的 `children` 如此递归下去，便形成了我们的树状结构 +`tree` 数据的生成采用了递归的方式，我们首先通过 `relations` 中的获取项目名，并将其引用的依赖作为当前节点的 `children`，在遍历 `children` 中的所有节点，将节点的引用的依赖作为该节点的 `children` 如此递归下去，便形成了我们的树状结构。 ### pkgs.json 文件 @@ -45,10 +45,33 @@ 1. `truth-cli` 对应的文件：[@truth-cli/core - genPkgs](https://github.com/truthRestorer/truth-cli/blob/main/packages/core/src/pkgs.ts)； -2. `pkgs.json` 文件的数据生成方式与 `tree` 图类似 +2. `pkgs.json` 文件的数据生成方式与 `tree` 图类似。 ::: `pkgs.json` 与 `tree` 有以下不同： 1. `tree` 引用的依赖在节点的 `children` 属性上，而 `pkgs.json` 引用的依赖在 `packages` 属性上 -2. 属性 `children` 是一个数组；属性 `packages` 是一个对象 \ No newline at end of file +2. 属性 `children` 是一个数组；属性 `packages` 是一个对象。 + + +### treePkgs.txt 文件 + +::: tip 前情提要 + +1. `truth-cli` 对应的文件：[@truth-cli/core - genPkgTree](https://github.com/truthRestorer/truth-cli/blob/main/packages/core/src/pkgTree.ts)； + +2. `treePkgs.txt` 文件的数据通过遍历 `pkgs` 形成。 +::: + +`treePkgs.txt` 的包含了以下字符： + +```ts +enum ESymbol { + TAB = ' ', // 空格字符 + VERTICAL = '│', // 竖线字符 + ADD = '├─', // 连接依赖的的添加字符 + LINE = '\n', // 换行字符 +} +``` + +我们做的无非是递归遍历 `pkgs`，通过一些规律将上述字符和依赖名连接起来。 diff --git a/docs/principle/optimize.md b/docs/about/optimize.md similarity index 100% rename from docs/principle/optimize.md rename to docs/about/optimize.md diff --git a/docs/guide/full.md b/docs/guide/full.md index 5c4f871b..dcb41dd7 100644 --- a/docs/guide/full.md +++ b/docs/guide/full.md @@ -5,88 +5,128 @@ ### --dep/-d ::: tip 功能介绍 -`--dep` 或者 `-d` 参数用于指定依赖引用关系的深度： +`--dep` 或者 `-d` 参数用于指定依赖引用关系的深度。 ::: -```bash +::: code-group +```bash [--dep] truth-cli analyze --dep 4 -# 等同于 truth-cli analyze -d 4 ``` +```bash [-d] +truth-cli analyze -d 4 +``` +::: ### --json/-j ::: tip 功能介绍 -`--json` 或者 `-j` 表示只会生成文件，参数值为生成文件的路径 +`--json` 或者 `-j` 表示只会生成文件，参数值为生成文件的路径。 ::: -```bash + +::: code-group +```bash [--json] truth-cli analyze --json -# 等同于 truth-cli analyze --j ``` +```bash [-j] +truth-cli analyze -j +``` +::: -默认情况下，会在根目录下生成 `pkgs.json` 文件，如果需要更改生成目录，可以在参数之后加上路径 -```bash +默认情况下，会在根目录下生成 `pkgs.json` 文件，如果需要更改生成目录，可以在参数之后加上路径： + +::: code-group +```bash [--json] truth-cli analyze --json dist/ ``` +```bash [-j] +truth-cli analyze -j dist/ +``` +::: -> **注意：请不要在路径开头加上 `/`，这会被 nodejs 识别为根路径，导致生成失败** +> **注意：请不要在路径开头加上 `/`，这会被 nodejs 识别为根路径，导致生成失败。** **结合 `dep` 参数：** ```bash truth-cli analyze --json --dep 3 ``` - +::: code-group +```bash [--json] +truth-cli analyze --json --dep 3 +``` +```bash [-j] +truth-cli analyze -j --dep 3 +``` +::: ### --both/-b ::: tip 功能介绍 -`--both` 或者 `-b` 参数表示生成文件并打开页面 +`--both` 或者 `-b` 参数表示生成文件并打开页面。 ::: -```bash +::: code-group +```bash [--both] truth-cli analyze --both -# 等同于 truth-cli analyze -b ``` +```bash [-b] +truth-cli analyze -b +``` +::: `--both` 参数的优先级是比 `--json` 大的，也就是说两者同时使用，优先考虑 `--both`： -```bash +::: code-group +```bash [--both] truth-cli analyze --both --json -# 等同于 truth-cli analyze --both ``` +```bash [-b] +truth-cli analyze -b --json +``` +::: **也可以指定 dep 参数** -```bash +::: code-group +```bash [--both] truth-cli analyze --both --dep 4 ``` +```bash [-b] +truth-cli analyze -b --dep 4 +``` +::: ## tree 命令 ::: tip 功能介绍 -tree 命令用于生成树形文件，简单的展示依赖之间的关系 +tree 命令用于生成树形文件，简单的展示依赖之间的关系。 ::: ```bash truth-cli tree ``` -**使用 `-d` 或 `--dep` 选项指定深度：** +**使用 `--dep` 或 `-d` 选项指定深度：** -```bash +::: code-group +```bash [--dep] truth-cli tree --dep 4 ``` +```bash [-d] +truth-cli tree -d 4 +``` +::: ## clean 命令 ::: tip 功能介绍 -clean 命令用于清理网页端所需要的文件 +clean 命令用于清理网页端所需要的文件。 ::: ```bash truth-cli clean ``` -我们已经对生成文件做了很多优化，通常情况下不会太大，如果你对磁盘空间很敏感，可以使用 `clean` 命令进行删除 +我们已经对生成文件做了很多优化，通常情况下不会太大，如果你对磁盘空间很敏感，可以使用 `clean` 命令进行删除。 diff --git a/docs/guide/index.md b/docs/guide/index.md index 36f80d0b..da47c6ca 100644 --- a/docs/guide/index.md +++ b/docs/guide/index.md @@ -2,20 +2,28 @@ ## 概述 -`truth-cli` 是一个分析 npm 依赖的命令行工具，它有以下特点 +`truth-cli` 是一个分析 npm 依赖的命令行工具，它有以下特点： -- 体积小、速度快：`truth-cli` 原始体积只有 `700kb` 左右，`i7-13700k` 平台下 `truth-cli` 项目的启动速度大约在 `40ms` 左右。 +- 体积小、速度快：`truth-cli` 原始体积只有 `700kb` 左右，`i7-13700k` 平台下 `truth-cli` 项目的启动速度大约在 `40ms` 左右； - 功能丰富：`truth-cli` 提供了网页可视化显示功能，也可以指定参数生成文件。 -`truth-cli` 不仅提供了命令行操作，也提供了 api 供用户自定义处理数据，详细请看 [@truth-cli/core](./api.md) +`truth-cli` 不仅提供了命令行操作，也提供了 api 供用户自定义处理数据，详细请看 [@truth-cli/core](./api.md)。 ## 安装 使用 NPM 全局安装 `truth-cli`： -```bash +::: code-group +```bash [npm] npm install -g truth-cli ``` +```bash [yarn] +yarn global add truth-cli +``` +```bash [pnpm] +pnpm install -g truth-cli +``` +::: ## 启动你的第一个 `truth-cli` 项目 @@ -27,16 +35,28 @@ truth-cli analyze 只生成文件： -```bash +::: code-group +```bash [--json] truth-cli analyze --json ``` +```bash [-j] +truth-cli analyze -j +``` +::: 启动网页并生成文件： -```bash +::: code-group +```bash [--both] truth-cli analyze --both ``` +```bash [-b] +truth-cli analyze -b +``` +::: ## Truth-cli 在线网页 -你可以访问 [Truth-cli on Vercel](truth-cli.vercel.app) 查看 `truth-cli` 的网页端效果 +你可以访问 [Truth-cli on Vercel](truth-cli.vercel.app) 查看 `truth-cli` 的网页端效果。 + +> 由于 `truth-cli` 采用的是 pnpm 管理工具，所以有些依赖无法展示清楚。 diff --git a/docs/index.md b/docs/index.md index 0a3001ce..61f62fae 100644 --- a/docs/index.md +++ b/docs/index.md @@ -18,7 +18,7 @@ features: - title: ⚡️体积小、速度快 details: 基于深度优先遍历算法的优化 - title: 🛠️功能丰富 - details: 可生成树形结构文本吗(灵感来自 tree 命令)以及 json 文件 + details: 可生成树形结构文本(灵感来自 tree 命令)以及 json 文件 - title: 📱可视化展示 details: web展示各个依赖之间的关系 ---