docs: update project documentation (#17)

Author: bakacai

.github/workflows/deploy-docs.yml

@@ -7,6 +7,8 @@ on:
       - main
     paths:
       - 'docs/**'
+    tags:
+      - 'v*'
   workflow_dispatch:
 
 permissions:
@@ -40,6 +42,12 @@ jobs:
           corepack enable
           pnpm install --frozen-lockfile
 
+      - name: Get version
+        run: |
+          RAW_VERSION=$(git describe --tags --abbrev=0 2>/dev/null || echo "dev")
+          VERSION=${RAW_VERSION#v}
+          echo "export const VERSION = '$VERSION'" > docs/src/.vuepress/version.ts
+
       - name: Build documentation
         env:
           NODE_OPTIONS: --max_old_space_size=8192

docs/.gitignore

@@ -3,3 +3,4 @@ node_modules/
 src/.vuepress/.cache/
 src/.vuepress/.temp/
 src/.vuepress/dist/
+src/.vuepress/version.ts

docs/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sftool-gui-docs",
-  "description": "一个界面友好的SIFLI系列芯片图形化烧录工具",
+  "description": "一个界面友好的SiFli系列芯片图形化烧录工具",
   "version": "1.1.3",
   "license": "Apache-2.0",
   "type": "module",

docs/src/.vuepress/config.ts

@@ -1,6 +1,8 @@
 import { defineUserConfig } from "vuepress";
+import { viteBundler } from "@vuepress/bundler-vite";
 
 import theme from "./theme.js";
+import { VERSION } from "./version.js";
 
 export default defineUserConfig({
   base: "/projects/sftool/",
@@ -20,6 +22,14 @@ export default defineUserConfig({
 
   theme,
 
+  bundler: viteBundler({
+    viteOptions: {
+      define: {
+        __VERSION__: JSON.stringify(VERSION),
+      },
+    },
+  }),
+
   head: [
     [
       'script',

docs/src/.vuepress/navbar/en.ts

@@ -2,30 +2,19 @@ import { navbar } from "vuepress-theme-hope";
 
 export const enNavbar = navbar([
   "/en/",
-  "/en/portfolio",
-  "/en/demo/",
   {
-    text: "Guide",
+    text: "Getting Started",
     icon: "lightbulb",
-    prefix: "/en/guide/",
-    children: [
-      {
-        text: "Bar",
-        icon: "lightbulb",
-        prefix: "bar/",
-        children: ["baz", { text: "...", icon: "ellipsis", link: "#" }],
-      },
-      {
-        text: "Foo",
-        icon: "lightbulb",
-        prefix: "foo/",
-        children: ["ray", { text: "...", icon: "ellipsis", link: "#" }],
-      },
-    ],
+    link: "/en/get-started/",
   },
   {
-    text: "V2 Docs",
-    icon: "book",
-    link: "https://theme-hope.vuejs.press/",
+    text: "Advanced Features",
+    icon: "fa-solid fa-sitemap",
+    link: "/en/Feature/",
+  },
+  {
+    text: "FAQs",
+    icon: "fa-solid fa-comment-dots",
+    link: "/en/FAQs/",
   },
 ]);

docs/src/.vuepress/navbar/zh.ts

@@ -7,19 +7,14 @@ export const zhNavbar = navbar([
     icon: "lightbulb",
     link: "/get-started/",
   },
-  {
-    text: "故障排除",
-    icon: "code",
-    link: "/Troubleshooting/",
-  },
   {
     text: "进阶功能",
     icon: "fa-solid fa-sitemap",
     link: "/Feature/",
   },
   {
     text: "常见问题",
-    icon: "fa-solid fa-wrench",
+    icon: "fa-solid fa-comment-dots",
     link: "/FAQs/",
   },
 ]);

docs/src/.vuepress/sidebar/en.ts

@@ -1,26 +1,7 @@
 import { sidebar } from "vuepress-theme-hope";
 
 export const enSidebar = sidebar({
-  "/en/": [
-    "",
-    "portfolio",
-    {
-      text: "Demo",
-      icon: "laptop-code",
-      prefix: "demo/",
-      link: "demo/",
-      children: "structure",
-    },
-    {
-      text: "Docs",
-      icon: "book",
-      prefix: "guide/",
-      children: "structure",
-    },
-    {
-      text: "Slides",
-      icon: "person-chalkboard",
-      link: "https://ecosystem.vuejs.press/plugins/markdown/revealjs/demo.html",
-    },
-  ],
+  "/en/get-started/": "structure",
+  "/en/source-build/": "structure",
+  "/en/custom/": "structure",
 });

docs/src/.vuepress/theme.ts

@@ -27,7 +27,7 @@ export default hopeTheme({
       // sidebar
       sidebar: enSidebar,
 
-      footer: "Default footer",
+      footer: "Apache-2.0 license | 2019 - 2026 SiFli Technologies(Nanjing) Co., Ltd",
 
       displayFooter: true,
 
@@ -46,7 +46,7 @@ export default hopeTheme({
       // sidebar
       sidebar: zhSidebar,
 
-      footer: "Apache-2.0 license | 2019 - 2025 思澈科技（南京）有限公司",
+      footer: "Apache-2.0 license | 2019 - 2026 思澈科技（南京）有限公司",
 
       displayFooter: true,
 

docs/src/FAQs/README.md

@@ -1,6 +1,8 @@
 ---
 title: 常见问题
-icon: fa-solid fa-wrench
+icon: fa-solid fa-comment-dots
 ---
 
-## 敬请期待
+## 1. 日志提示“Connected success!”但是“Download stub failed!”
+
+可能是芯片当前处于低功耗模式，此时芯片不会响应串口下载指令，请参考[进阶功能-行为设定](/Feature/README.md#行为设定)将连接前行为改为“软重启”

docs/src/Feature/README.md

@@ -1,6 +1,77 @@
 ---
 title: 进阶功能
-icon: fa-solid fa-wrench
+icon: fa-solid fa-sitemap
 ---
 
-## 即将呈现
+> sftool-gui 为高级用户提供了深度定制选项，支持自定义硬件驱动及复杂的连接行为控制。
+
+## stub配置
+
+::: info stub 机制说明
+sftool 在烧录过程中会先将一段 stub 程序下载至设备 RAM，随后由上位机与该 stub 进行交互，以完成 Flash 的读取、擦除与写入操作。
+:::
+
+### 驱动注入与硬件初始化
+
+stub 内置了主流 Flash 驱动。若您的硬件使用了非标准或较新的 Flash 颗粒，需通过此功能手动注入外部驱动：
+
+- Flash 设备：支持额外添加最多 12 组自定义 Flash 驱动，参数配置[参考链接](https://wiki.sifli.com/tools/flash/Flash%E9%85%8D%E7%BD%AE%E6%8C%87%E5%8D%97.html
+)。
+
+- SDIO 配置：支持 SDIO 接口配置，适用于 EMMC 或 TF 卡存储介质。
+
+- GPIO 管理：支持定义最多 12 条 GPIO 的高低电平初始化状态。
+
+- PMIC 管理：支持设置 SF30147 电压轨，确保硬件在烧录电压下稳定工作。
+
+### 生效与校验
+
+启用开关：完成配置后，必须在右侧勾选 `应用自定义设置`，否则软件将继续调用内置默认 stub。
+
+配置导入/导出：支持 JSON 格式的配置文件，便于在不同设备间迁移参数。
+
+校验机制：若填写的参数存在逻辑错误（如格式非法），`应用自定义设置` 开关将无法开启。
+
+![](image-1.png)
+
+## 行为设定
+
+您可以根据硬件的实时状态，自定义工具在连接与断开时的特定动作。
+
+![](image-2.png)
+
+### 连接前行为
+
+决定工具在尝试下载 stub 之前的动作：
+
+1. 重启（默认选项）
+
+- 逻辑：先发送复位指令，再执行 stub 下载。
+
+- 场景：适用于设备处于低功耗模式（睡眠）的情况。此时芯片不响应串口下载指令，必须通过复位将其唤醒。
+
+2. 不重启
+
+逻辑：不执行复位动作，直接尝试下载 stub 并建立连接。
+
+3. 不重启且不下载 stub
+
+- 逻辑：直接与内存中已有的 stub 建立二次连接。
+
+- 场景：极速连接模式。若上次断开连接时未重启设备，stub 仍驻留在 RAM 中，开启此项可大幅缩短连接耗时。
+
+### 断开前行为
+
+决定操作完成并点击“断开连接”后的设备状态：
+
+1. 软重启
+
+- 逻辑：断开后立即复位芯片。
+
+- 结果：RAM 中的 stub 会丢失，芯片开始运行 Flash 中的用户程序。固件烧录后通常选择此项以立即生效。
+
+2. 不重启（默认选项）
+
+- 逻辑：断开后不发送复位信号。
+
+- 结果：芯片继续保持在 stub 运行状态。此时新烧录的固件不会运行，方便您在不断电的情况下进行二次连接调试。