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 模型进行测试）
  • 添加注释：解释不明显的部分
  • 经过测试：确认示例可在当前版本中运行
from ultralytics import YOLO

# 加载预训练模型
model = YOLO("yolo26n.pt")

# 使用自定义数据进行训练
results = model.train(data="coco8.yaml", epochs=3)

图片和媒体#

存储在仓库中或使用 CDN：

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

尽量控制图片大小（尽可能小于 500KB）。

构建文档 🔨#

本地开发#

每个仓库都有自己的环境设置说明。对于本员工手册仓库，请使用以下命令安装依赖：

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)
        ```
    """

关键要素：

  • 简要说明：用一句话概述
  • 参数：包含类型的参数说明
  • 返回值：返回值说明
  • 示例：可运行的代码示例

添加新页面 📄#

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 的清单

最佳实践 ✅#

内容组织#

  • 逻辑结构：将相关内容归为一组
  • 渐进式呈现：由浅入深
  • 交叉链接：链接到相关页面
  • 搜索优化：使用清晰的标题和描述

维护#

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

无障碍访问#

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

资源 📚#

贡献者
glenn-jocherglenn-jocher6laodouyalaodouya1pderrengerpderrenger1