doc: Add Q&A docs (#1174)

* docs: 添加常见问题解答文档并更新工作流配置

- 新增questions目录及构建错误FAQ文档
- 更新文档翻译工作流触发分支为master和doc-*
- 优化PR创建时的提交信息格式

Signed-off-by: longjin <longjin@DragonOS.org>

* ci: 改进文档翻译工作流并添加失败处理

- 添加获取短SHA步骤用于PR标题
- 在翻译脚本中添加失败退出逻辑

Signed-off-by: longjin <longjin@DragonOS.org>

* docs: Translation update [b7b5ea2c] (#1173)

* Update translated documentation
---------

Co-authored-by: dragonosbot <bot@dragonos.org>

* 1

* 1

---------

Signed-off-by: longjin <longjin@DragonOS.org>
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Co-authored-by: dragonosbot <bot@dragonos.org>

.github/workflows/doc_translation.yml

@@ -2,55 +2,64 @@ name: Docs Translation
 
 on:
   push:
-    branches: [ master ]
+    branches: [master]
     paths:
-      - 'docs/**'
+      - "docs/**"
   workflow_dispatch:
 
 jobs:
   translate-and-pr:
     runs-on: ubuntu-latest
     steps:
-    - name: Checkout code
+      - name: Checkout code
-      uses: actions/checkout@v3
+        uses: actions/checkout@v3
-      with:
+        with:
-        fetch-depth: 0
+          fetch-depth: 0
 
-    - name: Set up Python
+      - id: get-short_sha
-      uses: actions/setup-python@v5
+        uses: actions/github-script@v7.0.1
-      with:
+        with:
-        python-version: '3.10'
+          script: |
+            const short_sha = context.sha.substring(0, 8)
+            core.setOutput('short_sha', short_sha)
 
-    - name: Install dependencies
+      - name: Set up Python
-      run: |
+        uses: actions/setup-python@v5
-        python -m pip install --upgrade pip
+        with:
-        pip install -r docs/requirements.txt
+          python-version: "3.10"
 
-    - name: Run document translator
+      - name: Install dependencies
-      run: python tools/doc_translator.py
+        run: |
-      env:
+          python -m pip install --upgrade pip
-        MAX_WORKERS: 20
+          pip install -r docs/requirements.txt
-        OPENAI_API_KEY: ${{ secrets.DRAGONOS_OPENAI_API_KEY }}
-        OPENAI_MODEL: Qwen/Qwen3-8B
-        OPENAI_BASE_URL: ${{ secrets.DRAGONOS_OPENAI_API_BASE }}
 
-    - name: Commit translated files
+      - name: Run document translator
-      run: |
+        run: python tools/doc_translator.py
-        git config --global user.name "dragonosbot"
+        env:
-        git config --global user.email "bot@dragonos.org"
+          MAX_WORKERS: 20
-        git add docs/locales/
+          OPENAI_API_KEY: ${{ secrets.DRAGONOS_OPENAI_API_KEY }}
-        git commit -m "Update translated documentation" || echo "No changes to commit"
+          OPENAI_MODEL: Qwen/Qwen3-8B
+          OPENAI_BASE_URL: ${{ secrets.DRAGONOS_OPENAI_API_BASE }}
 
-    - name: Create Pull Request
+      - name: Commit translated files
-      uses: peter-evans/create-pull-request@v5
+        run: |
-      with:
+          git config --global user.name "dragonosbot"
-        commit-message: "Update translated documentation"
+          git config --global user.email "bot@dragonos.org"
-        title: "docs: Automatic translation update"
+          git add docs/locales/
-        body: "Automated translation update triggered by docs changes"
+          git commit -m "Update translated documentation" || echo "No changes to commit"
-        branch: "dragonosbot/docs-translation-update"
+
-        branch-suffix: "timestamp"
+      - name: Create Pull Request
-        base: master
+        uses: peter-evans/create-pull-request@v5
-        author: dragonosbot <dragonosbot@dragonos.org>
+        with:
-        delete-branch: true
+          commit-message: "Update translated documentation"
-        reviewers: fslongjin
+          title: "docs: Translation update [${{steps.get-short_sha.outputs.short_sha}}]"
-        assignees: fslongjin
+          body: |
+            Automated translation update triggered by docs changes
+            Commit: ${{ github.sha }}
+          branch: "dragonosbot/docs-translation-update"
+          branch-suffix: "timestamp"
+          base: ${{ github.ref_name }}
+          author: bot <bot@dragonos.org>
+          delete-branch: true
+          reviewers: fslongjin
+          assignees: fslongjin

docs/.translation_cache.json

@@ -264,6 +264,12 @@
     "hash": "8b840ec6af5782d8f793f746b1061ed9"
   },
   "en:index.rst": {
-    "hash": "8ca31b793978d962c65df867b3261860"
+    "hash": "9bdd33a9fc7a2648cded2d463fe29115"
+  },
+  "en:questions/index.rst": {
+    "hash": "b1cee9bfde04d6375f24c93a29ce3c71"
+  },
+  "en:questions/build_errors.md": {
+    "hash": "76bf24821bab907c28e8c8287d2895d5"
   }
 }

docs/index.rst

@@ -56,6 +56,13 @@
    
    userland/appdev/index
 
+.. toctree::
+   :maxdepth: 1
+   :caption: Q&A
+   
+   questions/index
+
+
 
 .. toctree::
    :maxdepth: 1

docs/locales/en/index.rst

@@ -6,7 +6,7 @@ English
 
    - Source document: index.rst
 
-   - Translation time: 2025-05-19 02:12:15
+   - Translation time: 2025-05-22 09:21:59
 
    - Translation model: `Qwen/Qwen3-8B`
 
@@ -53,6 +53,12 @@ English
 
    userland/appdev/index
 
+.. toctree::
+   :maxdepth: 1
+   :caption: Q&A
+
+   questions/index
+
 .. toctree::
    :maxdepth: 1
    :caption: DragonOS Community

docs/locales/en/questions/build_errors.md

@@ -0,0 +1,55 @@
+:::{note}
+**AI Translation Notice**
+
+This document was automatically translated by `Qwen/Qwen3-8B` model, for reference only.
+
+- Source document: questions/build_errors.md
+
+- Translation time: 2025-05-22 09:22:00
+
+- Translation model: `Qwen/Qwen3-8B`
+
+Please report issues via [Community Channel](https://github.com/DragonOS-Community/DragonOS/issues)
+
+:::
+
+# Common Issues During Build
+
+Common issues encountered during the build of DragonOS and their solutions.
+
+## 1. Error Indicates Missing Toolchain
+
+### Question Detail
+
+During the build, if you encounter an error like ``xxxx not found``, it is typically due to the absence of the necessary compiler toolchain.
+
+### Answer
+
+If you were previously able to compile the code, but after pulling the latest code, you encounter this error, it is likely because the upstream code has updated its requirements for the toolchain. You can try the following steps to resolve this issue:
+
+```shell
+cd tools
+bash bootstrap.sh
+```
+
+Then, restart the terminal and re-run the build command.
+
+*Note:* The ``bootstrap.sh`` script is designed to be "re-runnable". It can be executed at any time to install the latest required toolchain on your system.
+
+## 2. Disk Image Write Failure
+
+### Question Detail
+
+- During the build of user programs, the content inside the disk image is inconsistent with the actual content.
+- Errors related to symbolic links are reported.
+- Some applications are not correctly installed into the image.
+
+### Answer
+
+If you encounter a disk image write failure during the build process, it could be due to insufficient disk space or permission issues. It could also be due to changes in directory attributes.
+
+A typical example is when a folder under ``bin/sysroot/xxx`` is actually a directory, but the new version of the application expects the directory ``xxx`` to be treated as a symbolic link.
+
+In such a case, you can first check whether there is an issue with the script used to compile your application. If you confirm that there is no problem, you can try the following steps:
+
+- Delete the ``bin/`` directory and rebuild. This can resolve most of the issues.

docs/locales/en/questions/index.rst

@@ -0,0 +1,21 @@
+.. note:: AI Translation Notice
+
+   This document was automatically translated by `Qwen/Qwen3-8B` model, for reference only.
+
+   - Source document: questions/index.rst
+
+   - Translation time: 2025-05-22 09:21:58
+
+   - Translation model: `Qwen/Qwen3-8B`
+
+
+   Please report issues via `Community Channel <https://github.com/DragonOS-Community/DragonOS/issues>`_
+
+Frequently Asked Questions
+====================================
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Contents
+
+   build_errors

docs/questions/build_errors.md

@@ -0,0 +1,44 @@
+# 构建错误常见问题解答
+
+在构建DragonOS时遇到的常见问题及其解决方法。
+
+
+## 1. 报错信息指示工具链缺失
+
+### question detail
+
+在构建中，如果出现比如`xxxx not found`这样的报错信息，通常是因为缺少必要的编译工具链。
+
+### Answer
+
+如果你之前是可以编译的，但是在拉取最新的代码后，出现了这个错误,那么大概率是因为上游代码更新了对工具链的要求。你可以尝试以下步骤来解决这个问题：
+
+```shell
+cd tools
+bash bootstrap.sh
+```
+
+接着，重启终端并重新运行构建命令。
+
+*Note:* `bootstrap.sh`脚本被设计为：“可重复运行”的。他可以在任何时间点运行，把当前最新需要的工具链，安装到你的系统中。
+
+## 2. 磁盘镜像写入失败了
+
+### question detail
+
+- 构建用户程序的时候，磁盘镜像里面的内容跟实际的不一致。
+- 报错符号链接相关的错误信息
+- 某些应用程序没有正确安装到镜像中
+
+### Answer
+
+
+在构建过程中，如果遇到磁盘镜像写入失败的问题，可能是由于磁盘空间不足或者权限问题。或者是目录属性有些改变。
+
+一种典型的例子，`bin/sysroot/xxx`下面的某个文件夹是个实际的目录，但是新版的应用程序期望把目录`xxx`当作一个符号链接来使用。
+
+对于这种情形，你可以先检查自己的应用程序编译的脚本是否有问题。如果确认没有问题，那么可以尝试以下步骤：
+
+- 删掉`bin/`目录，然后重新构建。这能够解决大部分的问题。
+
+

docs/questions/index.rst

@@ -0,0 +1,8 @@
+常见问题解答
+====================================
+   
+.. toctree::
+   :maxdepth: 1
+   :caption: 目录
+
+   build_errors

tools/doc_translator.py

@@ -22,6 +22,7 @@ import re
 import hashlib
 import json
 from pathlib import Path
+import sys
 import threading
 from typing import List, Dict, Tuple
 import openai
@@ -454,6 +455,7 @@ class DocumentTranslator:
         lang_pbar.close()
         print(
             f"\n翻译完成！ Succ: {total_tasks-self.fail_count}, Fail: {self.fail_count}")
+        
 
 
 if __name__ == "__main__":
@@ -465,3 +467,6 @@ if __name__ == "__main__":
 
     translator = DocumentTranslator()
     translator.run()
+    
+    if translator.fail_count > 0:
+        sys.exit(1)