文档编写指南

本指南概述了在代码库及补充文件中书写和维护文档的最佳实践。

---

In-Code Documentation (Docstrings)

文档字符串对于理解代码的目的、用法和行为至关重要。请遵守以下约定：

一般规则

• 文档 所有公共类、方法和函数 使用 docstrings。

• 使用 Sphinx-style 文档字符串。

• 不要在docstring中包含参数类型——它们应使用类型提示在函数签名中声明。

Format and Directives

使用以下指令来描述不同元素：

• :param <name>: — 描述一个参数。

• :return: — Describe the return value.

• :raises <exception>: — 描述函数可能引发的异常。

样例

def add(a: int, b: int) -> int:
    """
    Add two integers.

    :param a: The first integer.
    :param b: The second integer.
    :return: The sum of the two integers.
    :raises ValueError: If either input is not an integer.
    """
    if not isinstance(a, int) or not isinstance(b, int):
        raise ValueError("Inputs must be integers.")
    return a + b

---

外部文档 (docs/ 目录)

所有项目级文档都位于 docs/ 目录中。这些文档通过提供指南、示例和参考资料，为用户和开发者提供支持。

格式

• Markdown (.md) 或 Jupyter Notebooks (.ipynb) 进行文档编写。

• Markdown 更适合用于叙述性内容和静态文档。

• 使用 Jupyter Notebooks 创建可执行的交互式内容（例如教程或演示）。

Jupyter Notebook 指南

• 确保所有笔记本都完全可执行。

• 始终运行所有单元格并保存输出再提交。

• 我们的CI/CD环境不支持GPU执行，因此笔记本文件必须在本地预先执行。

Markdown & Notebook Directives

使用以下模式进行丰富格式化:

• [name](#ref) — 内部交叉引用，例如 [ModuleBase](#evox.core.module.ModuleBase) 或 [ModuleBase](#ModuleBase)

• ![替代文本](path) — 嵌入图片，例如，![Module base](/_static/modulebase.png)

---

翻译

文档支持多语言内容。按照以下步骤更新或生成翻译。

更新翻译（例如，针对 zh_CN）

cd docs
make gettext
sphinx-intl update -p build/gettext -l zh_CN
cd ..
python docs/fix_output.py