Ultralytics YOLO27：

文档工作流 📚#

本指南介绍如何为 Ultralytics 项目编写、构建和维护文档。

文档结构 🗂️#

主要文档网站#

仓库结构#

内容所有权和页面系列因仓库而异。请遵循现有的层级结构和导航清单，不要假定文件夹集合是固定的。典型的源代码树从以下内容开始：

docs/
└── en/              # Source content

编写文档 ✍️#

风格指南#

  • 清晰简洁：快速切入重点
  • 主动语态：使用“训练模型”，而不是“模型被训练”
  • 代码示例：为每个概念提供可运行的代码
  • 视觉辅助：在有帮助的地方使用图像或示意图
  • 格式一致：遵循现有页面结构

Markdown 格式#

---
description: Brief page description for SEO
keywords: relevant, keywords, for, search
---

# Page Title

Brief introduction explaining what this page covers.

## Section Heading

Content with examples:

```python
from ultralytics import YOLO

# Load pretrained model
model = YOLO("yolo26n.pt")
results = model("image.jpg")
```

### Key points:

- Use bullet points for lists
- Keep paragraphs short
- Include links to related pages

代码示例#

  • 精简：仅展示相关代码
  • 可运行：示例应能复制粘贴即可运行（使用实际的 YOLO models 进行测试）
  • 有注释：解释不易理解的部分
  • 经过测试：验证示例在当前版本下可用
from ultralytics import YOLO

# Load pretrained model
model = YOLO("yolo26n.pt")

# Train on custom data
results = model.train(data="coco8.yaml", epochs=3)

图像和媒体#

存储在仓库中或使用 CDN：

![Alt text](https://path/to/image.png)

尽量控制图像大小（<500KB）。

构建文档 🔨#

本地开发#

每个仓库都会记录自己的环境设置。对于本 Handbook 仓库，请使用以下命令安装依赖：

uv pip install -r requirements.txt

在本地构建并运行：

zensical serve

访问 http://127.0.0.1:8000 进行预览。

Zensical 配置#

代码仓库使用过渡性的、兼容 Zensical 的 mkdocs.yml 清单。有关此仓库的当前配置，请参阅根目录 mkdocs.yml。

API 文档 📖#

API 参考文档根据文档字符串自动生成。请参阅完整 API 参考了解所有模块：

def train(self, data, epochs=100, batch=16):
    """
    Train the model on a dataset.

    Args:
        data (str): Path to data YAML file
        epochs (int): Number of training epochs
        batch (int): Batch size

    Returns:
        (Results): Training results

    Examples:
        ```python
        model = YOLO("yolo26n.pt")
        results = model.train(data="coco8.yaml", epochs=100)
        ```
    """

关键元素：

  • 简要描述：一行摘要
  • Args：包含类型的参数描述
  • Returns：返回值描述
  • Examples：可运行的代码示例

添加新页面 📄#

1. 创建 Markdown 文件#

# Create new guide
touch docs/en/guides/new-guide.md

2. 更新导航#

编辑 mkdocs.yml：

nav:
    - Home: index.md
    - Guides:
          - New Guide: guides/new-guide.md

3. 编写内容#

遵循风格指南并包含示例。

4. 测试构建#

zensical build --strict

5. 提交 PR#

按照开发工作流执行 PR 流程。

翻译 🌐#

翻译内容会在集中式生产构建期间从英文内容生成。不要手动添加翻译源目录。

翻译指南#

  • 保留英文技术术语（YOLO、mAP、FPS）
  • 翻译描述和说明
  • 保持与英文版本相同的结构
  • 英文版本变更时更新翻译

文档 CI 🤖#

CI 会自动：

  • 在每个 PR 上运行 zensical build --strict
  • 检查失效链接
  • 验证 Markdown 格式
  • 合并到 main 后触发集中式生产构建

修复构建错误#

常见问题：

  • 失效链接：修复或移除无效链接
  • 缺少图像：添加图像或更新路径
  • 无效 YAML：修复 frontmatter 语法
  • 配置错误：检查兼容 Zensical 的清单

最佳实践 ✅#

内容组织#

  • 逻辑结构：将相关内容分组
  • 渐进式展开：从简单到高级
  • 交叉链接：链接到相关页面
  • 搜索优化：使用清晰的标题和描述

维护#

  • 保持最新：针对新功能进行更新
  • 移除过时内容：删除已弃用的内容
  • 检查链接：定期修复失效链接
  • 用户反馈：解决常见问题

无障碍访问#

  • 替代文本：为屏幕阅读器描述图像
  • 清晰的标题：使用正确的标题层级
  • 通俗语言：尽可能避免术语
  • 代码对比度：确保代码块清晰易读

资源 📚#

贡献者
GLglenn-jocher6LAlaodouya1PDpderrenger1