文档开发¶

本指南介绍如何在本地构建文档、添加新页面以及贡献翻译。

前置要求¶

已安装 Python 3.9+
pip 包管理器

本地构建文档¶

安装依赖¶

cd docs
pip install -r requirements.txt

构建英文文档¶

make html

输出生成在 docs/_build/html/en/ 目录中。在浏览器中打开 docs/_build/html/en/index.html。

构建中文文档¶

make html-zh

输出生成在 docs/_build/html/zh/ 目录中。

构建双语文档¶

make html-all

清理构建产物¶

make clean

添加新页面¶

在相应目录中创建 Markdown 文件：

# Example: adding a new guide
touch docs/usage/new-feature.md

使用 MyST Markdown 语法编写内容：

# New Feature

Description of the new feature.

## Section Title

Content goes here.

在 docs/index.md 中添加到目录：

```{toctree}
:maxdepth: 2
:caption: Usage & Features

usage/features
usage/configuration
usage/api-reference
usage/new-feature
```

在本地构建并验证：
```
make html
```

MyST Markdown 语法¶

InnoClaw 文档使用 MyST-Parser 在 Sphinx 中支持 Markdown。

提示框¶

:::{note}
This is a note.
:::

:::{warning}
This is a warning.
:::

:::{tip}
This is a tip.
:::

:::{important}
This is important.
:::

Mermaid 图表¶

```{mermaid}
graph LR
    A --> B --> C
```

表格¶

| Column 1 | Column 2 |
|----------|----------|
| Value 1  | Value 2  |

交叉引用¶

See [Installation Guide](getting-started/installation.md) for details.

翻译工作流¶

InnoClaw 文档使用 Sphinx 内置的国际化（i18n）功能和 sphinx-intl。

工作原理¶

英文（.md）文件是唯一真实来源
Sphinx 将可翻译的字符串提取到 .pot 模板文件中
sphinx-intl 为每种语言生成 .po 翻译文件
翻译者编辑 .po 文件以添加翻译
Sphinx 使用 .po 文件构建翻译后的文档

更新翻译¶

修改英文源文件后，更新翻译文件：

# Step 1: Extract translatable strings
make gettext

# Step 2: Update .po files for Chinese
make update-po

这将使用新的或更改的字符串更新 docs/locales/zh/LC_MESSAGES/*.po 文件。

编辑翻译¶

使用文本编辑器或 PO 编辑器（如 Poedit）打开 docs/locales/zh/LC_MESSAGES/ 中的 .po 文件：

#: ../../getting-started/overview.md:3
msgid "What is InnoClaw?"
msgstr "什么是 InnoClaw？"

每个条目包含：

msgid —— 原始英文文本
msgstr —— 中文翻译（在此填写）

构建翻译后的文档¶

make html-zh

翻译检查清单¶

运行 make gettext 提取字符串
运行 make update-po 更新 .po 文件
翻译 .po 文件中所有的 msgstr 条目
运行 make html-zh 验证构建
检查输出中是否有未翻译的字符串

文件结构¶

docs/
├── conf.py                  # Sphinx configuration
├── index.md                 # Root index
├── requirements.txt         # Python dependencies
├── Makefile                 # Build commands
├── _static/                 # Custom CSS, images
├── _templates/              # Custom templates
├── getting-started/         # Getting started guides
├── usage/                   # Usage documentation
├── notifications/           # Bot integration docs
├── development/             # Developer guides
├── troubleshooting/         # FAQ and troubleshooting
└── locales/                 # Translation files
    └── zh/
        └── LC_MESSAGES/
            └── *.po         # Chinese translations