Sphinx 文档项目规范

这些最佳实践源于真实项目的丰富经验。遵循既定的约定可以使您的文档更具可读性，同时通过已验证的模式帮助您避免常见的陷阱。

本指南展示了通过多年使用 Sphinx-doc、构建包含 API 参考、层次结构和多语言支持的复杂文档系统所开发的最佳实践。通过遵循这些建议，您可以显著减少重复性工作，专注于创建有价值的内容。

文件组织

以逻辑层次结构组织您的 Sphinx 文档。典型的结构可能如下：

docs/
├── source/             # 源文件 (.rst, .md, .ipynb)
│   ├── _static/        # 静态文件 (CSS, 图片)
│   ├── _templates/     # 自定义模板
│   ├── conf.py         # Sphinx 配置
│   ├── index.rst       # 主入口点
│   ├── installation/   # 章节目录
│   │   └── index.rst
│   ├── usage/
│   │   └── index.rst
│   └── api/            # API 文档（可自动生成）
│       └── ...
└── build/              # 生成的输出 (HTML, PDF 等)
    └── html/           # 生成的 HTML 文件

命名约定

为了保持一致、可维护的文档：

  1. 文件名和目录中避免使用空格 - 使用连字符或下划线代替

  2. 优先使用连字符而非下划线 - 连字符在 URL 中有效，而下划线可能会导致问题

  3. 对文件和目录名使用 kebab-case 命名法 - 例如，使用 user-guide.rst 而非 UserGuide.rst

  4. 坚持使用 ASCII 字符 - 尽可能使用英文名称和字母数字字符

  5. 保持一致性 - 选择一种命名约定并在整个项目中应用它

页面组织

推荐：使用基于文件夹的结构

与其使用包含许多 .rst 文件的平面层次结构，不如将每个主要文档章节组织为带有索引文件的文件夹：

# 推荐
docs/source/
├── user-guide/           # "用户指南"章节的目录
│   ├── index.rst         # 主要内容（相当于 user-guide.rst）
│   ├── images/           # 章节特定的图片
│   │   ├── screenshot1.png
│   │   └── diagram.png
│   └── examples/         # 额外的子章节文件
│       └── index.rst
└── index.rst             # 根文档

而不是：

# 不推荐
docs/source/
├── user-guide.rst        # 单个文件
├── screenshot1.png       # 图片与文档混合
├── diagram.png
├── examples.rst
└── index.rst             # 根文档

基于文件夹组织的好处：

  1. 更好的组织 - 相关内容保持在一起

  2. 可扩展性 - 易于添加子章节和资源

  3. 改进的导航 - 为读者提供逻辑层次结构

  4. 可维护性 - 更容易管理相关资源

  5. 更整洁的目录 - 没有文档和资源的混合

图片管理

为了一致且可维护的图片处理：

  1. 在每个文档章节内创建 images/ 子目录：

docs/source/user-guide/
├── images/
│   ├── screenshot1.png
│   └── diagram.png
└── index.rst

  1. 使用相对路径引用图片：

.. image:: ./images/screenshot1.png
   :alt: 应用程序截图
   :width: 80%

  1. 一致命名 - 为图片使用描述性的、带连字符的名称

  2. 优化图片 - 压缩图片以减小大小而不牺牲质量

  3. 适当的替代文本 - 始终包含描述性替代文本以提高可访问性

  4. 版本控制 - 在界面变更时更新图片，保持与文本的一致性

多语言支持

如果您希望每个 HTML 页面都支持多种语言，官方方法过于复杂，不推荐使用。基本上它的做法是：

  1. 使用 gentext 插件 将文档翻译成目标语言 - 但是，翻译质量很差。

  2. 使用 readthedocs.org 上的多语言功能，但这需要维护多个 Git 仓库，这使得它们难以保持同步。

相反，我建议遵循 页面组织 中定义的样式，并使用像 _es.rst 或 _cn.rst 这样的后缀来表示同一文档的不同语言版本。您的文件结构可能如下所示：

tutorial
|--- index.rst      # 英语（默认）
|--- index_es.rst   # 西班牙语
|--- index_cn.rst   # 中文

在每个 .rst 文件的开头，定义一个引用链接，如 .. _en_tutorial:、.. _es_tutorial: 或 .. _cn_tutorial:。然后，在顶级标题下插入以下片段，作为语言切换器：

- :ref:`English <en_tutorial>`
- :ref:`española <es_tutorial>`
- :ref:`中文 <cn_tutorial>`

当您需要为非默认（非英语）子文档使用 .. autotoctree:: 时，可以使用 :index_file: 选项指定特定语言的索引文件，如下所示：

.. autotoctree::
    :maxdepth: 1
    :index_file: index_cn.rst