chore(docs): optimize the brief docs (#492)

web-infra-dev · Sep 1, 2024 · 5ea52cd · 5ea52cd
1 parent 58ea26c
commit 5ea52cd
Show file tree

Hide file tree

Showing 8 changed files with 360 additions and 73 deletions.
diff --git a/packages/document/docs/en/config/options/options.mdx b/packages/document/docs/en/config/options/options.mdx
@@ -1,3 +1,5 @@
+import { Badge } from '@theme';
+
 # Options
 
 ## RsdoctorRspackPlugin
@@ -137,18 +139,22 @@ import FeaturesRspack from '@en/shared/features-rspack.md';
 
 ### mode
 
+<Badge text="Version: 0.4.0" type="warning" />
+
 - **Type:** `normal | brief | lite`
 - **Optional:** `true`
 - **Default:** `normal`
 
 Choose the Rsdoctor build report mode to use, which includes the following options:
 
-- normal: Normal mode, which generates a '.rsdoctor' folder in the build output directory. It contains different data files and the report page displays code. The output directory can be configured using [reportDir](#reportdir).
-- brief: Brief mode, which generates an HTML report file in the `.rsdoctor` folder of the build output directory. You can open this HTML file in a browser to view the report. Brief mode also has additional configuration options, see [brief](#brief).
-- lite: Lite mode, which is a mode based on normal mode that does not display source code and bundles codes. It only displays information about the built codes.
+import ModeIntro from '@en/shared/mode-intro.md';
+
+<ModeIntro />
 
 ### reportDir
 
+<Badge text="Version: 0.4.0" type="warning" />
+
 - **Type:** string
 - **Optional:** `true`
 - **Default:** undefined
@@ -157,6 +163,8 @@ The output directory for Rsdoctor reports. By default, it is the build output di
 
 ### brief
 
+<Badge text="Version: 0.4.0" type="warning" />
+
 - **Type:** [BriefType](#brieftype)
 - **Optional:** `true`
 - **Default:** undefined

diff --git a/packages/document/docs/en/guide/start/cicd.mdx b/packages/document/docs/en/guide/start/cicd.mdx
@@ -1,3 +1,5 @@
+import { Badge } from '@theme';
+
 # CI/CD Tutorial
 
 In CI/CD, there is often a desire to upload historical reports to the CDN as historical records. Because it's not convenient to achieve instant use in the standard mode, the **Brief** mode is supported.
@@ -8,7 +10,9 @@ In Brief mode, data reports are integrated into a single HTML page, making it ea
 
 ### Enabling Brief Mode
 
-You can enable Brief mode by configuring the `mode.brief` option in the Rsdoctor plugin. After the build, Brief mode will generate a report in the build output directory: `[outputDir]/.rsdoctor/report-rsdoctor.html`. You can view the build analysis summary by opening the HTML file in a browser.
+<Badge text="Version: 0.4.0" type="warning" />
+
+You can enable Brief mode by configuring the [mode.brief](/config/options/options#mode) option in the Rsdoctor plugin. After the build, Brief mode will generate a report in the build output directory: `[outputDir]/.rsdoctor/report-rsdoctor.html`. You can view the build analysis summary by opening the HTML file in a browser.
 
 - In Brief mode, no code data is displayed to prevent the page from crashing due to large data sizes.
 - The report output directory and file name can be configured. Refer to: [Options](/config/options/options#brief).
@@ -28,3 +32,11 @@ module.exports = {
   ].filter(Boolean),
 };
 ```
+
+### Differences between Brief Mode and Lite Mode
+
+Currently, Rsdoctor has several report modes: `Normal, Brief, and Lite`.
+
+import ModeIntro from '@en/shared/mode-intro.md';
+
+<ModeIntro />
diff --git a/packages/document/docs/en/shared/mode-intro.md b/packages/document/docs/en/shared/mode-intro.md
@@ -0,0 +1,5 @@
+- **normal mode:** Generates a `.rsdoctor` folder in the build output directory, which contains various data files and displays code in the report page. The output directory can be configured via [reportDir](/config/options/options#reportdir).
+
+- **brief mode:** Generates an HTML report file in the `.rsdoctor` folder within the build output directory. All build analysis data will be consolidated into this HTML file, which can be viewed by opening it in a browser. Brief mode also has additional configuration options, detailed at: [brief](/config/options/options#brief).
+
+- **lite mode:** Based on the normal mode, this mode does not display source code and product code, only showing the information of the bundled code.
diff --git a/packages/document/docs/zh/config/options/options.mdx b/packages/document/docs/zh/config/options/options.mdx
@@ -1,3 +1,5 @@
+import { Badge } from '@theme';
+
 # Options 配置
 
 ## RsdoctorRspackPlugin 插件
@@ -139,18 +141,22 @@ import FeaturesRspack from '@zh/shared/features-rspack.md';
 
 ### mode
 
+<Badge text="Version: 0.4.0" type="warning" />
+
 - **Type:** `normal | brief | lite`
 - **Optional:** `true`
 - **Default:** `normal`
 
 选择使用的 Rsdoctor 构建报告模式，有以下几种：
 
-- normal：普通模式，会在构建产物目录生成 '.rsdoctor' 文件夹，里面会有不同的数据文件，报告页面中会有代码展示。输出目录可配置：[reportDir](#reportdir).
-- brief: 简报模式，会在构建产物目录的 '.rsdoctor' 文件夹中生成一个 HTML 报告文件，可通过在浏览器中打开这个 HTML 查看报告.brief 模式还有更多配置项，查看：[brief](#brief)
-- lite: 轻量模式，这个模式是在普通模式基础下不展示源码和产物代码的模式，只展示打包后的代码信息。
+import ModeIntro from '@zh/shared/mode-intro.md';
+
+<ModeIntro />
 
 ### reportDir
 
+<Badge text="Version: 0.4.0" type="warning" />
+
 - **Type:** string
 - **Optional:** `true`
 - **Default:** undefined
@@ -159,6 +165,8 @@ Rsdoctor 报告输出目录，默认是构建产物输出目录。
 
 ### brief
 
+<Badge text="Version: 0.4.0" type="warning" />
+
 - **Type:** [BriefType](#brieftype)
 - **Optional:** `true`
 - **Default:** undefined

diff --git a/packages/document/docs/zh/guide/start/cicd.mdx b/packages/document/docs/zh/guide/start/cicd.mdx
@@ -1,3 +1,5 @@
+import { Badge } from '@theme';
+
 # CI/CD 使用教程
 
 CI/CD 中，往往想要上报历史报告到 CDN 作为历史记录，因为普通模式下无法便捷的做到即开即用，所以支持了 **Brief** 模式。
@@ -8,7 +10,9 @@ Brief 模式中，会将数据报告整合到一个 HTML 页面中，方便用
 
 ### 开启 Brief 模式
 
-通过配置 Rsdoctor 插件的 `mode.brief` 选项，即可开启 Brief 模式。Brief 模式会在构建后生成一份报告到构建产物目录中： `[outputDir]/.rsdoctor/report-rsdoctor.html`，通过浏览器打开 HTML 文件，
+<Badge text="Version: 0.4.0" type="warning" />
+
+通过配置 Rsdoctor 插件的 [mode.brief](/config/options/options#mode) 选项，即可开启 Brief 模式。Brief 模式会在构建后生成一份报告到构建产物目录中： `[outputDir]/.rsdoctor/report-rsdoctor.html`，通过浏览器打开 HTML 文件，
 即可看到构建分析简报。
 
 - Brief 模式下是不展示任何的代码数据的，为了防止数据过大导致页面崩溃。
@@ -30,3 +34,11 @@ module.exports = {
   ].filter(Boolean),
 };
 ```
+
+### Brief 模式和 Lite 模式的区别
+
+目前 Rsdoctor 有几种报告模式：`Normal、Brief 和 Lite`。
+
+import ModeIntro from '@zh/shared/mode-intro.md';
+
+<ModeIntro />
diff --git a/packages/document/docs/zh/shared/mode-intro.md b/packages/document/docs/zh/shared/mode-intro.md
@@ -0,0 +1,5 @@
+- **normal 模式：** 在构建产物目录中生成一个 `.rsdoctor` 文件夹，其中包含各种数据文件，并在报告页面中展示代码。输出目录可以通过 [reportDir](/config/options/options#reportdir) 进行配置。
+
+- **brief 模式：** 在构建产物目录的 `.rsdoctor` 文件夹中生成一个 HTML 报告文件，所有构建分析数据会整合注入到这个 HTML 文件中，可以通过浏览器打开该 HTML 文件查看报告。brief 模式还有更多配置项，详细信息请参阅：[brief](/config/options/options#brief).
+
+- **lite 模式：** 基于普通模式，不展示源码和产物代码，仅显示打包后的代码信息。
diff --git a/packages/document/package.json b/packages/document/package.json
@@ -38,6 +38,6 @@
   "dependencies": {
     "react-markdown": "^9.0.1",
     "@rstack-dev/doc-ui": "^1.2.0",
-    "rspress": "^1.26.3"
+    "rspress": "^1.28.2"
   }
 }