Read the Docs 文档托管平台使用教程

什么是Read the Docs？

Read the Docs 是一个开源的文档托管平台，专门为技术文档提供自动化构建和托管服务。它支持多种文档格式（如Sphinx、MkDocs等），能够自动从代码仓库拉取文档源码，构建成可浏览的HTML网页，并提供PDF/EPUB等格式下载。

准备工作

1. 文档项目结构要求

在开始使用Read the Docs前，您的文档项目需要满足以下基本结构要求：

• 必须包含文档构建配置文件（如Sphinx的conf.py或MkDocs的mkdocs.yml）
• 推荐使用.readthedocs.yaml作为构建配置文件
• 文档源文件应放在专门的目录中（如docs/）

2. 创建示例项目

对于初学者，可以按照以下步骤创建一个简单的Sphinx文档项目：

1. 安装Sphinx：pip install sphinx
2. 初始化项目：sphinx-quickstart docs
3. 添加示例内容并构建：make html

注册Read the Docs账号

1. 访问Read the Docs官网
2. 点击"Sign up"注册账号
3. 推荐使用GitHub账号关联登录（便于后续集成）

导入项目到Read the Docs

1. 连接代码仓库

1. 登录Read the Docs控制台
2. 点击"Import a Project"按钮
3. 选择您的代码仓库（支持GitHub、GitLab等）
4. 填写项目基本信息：
   • 项目名称（将用于生成子域名）
   • 仓库URL
   • 默认分支

2. 首次构建

项目导入后，Read the Docs会自动触发首次构建：

1. 系统会拉取代码仓库内容
2. 根据配置文件安装依赖
3. 执行文档构建命令
4. 生成HTML等格式的文档

构建完成后，您可以通过提供的URL访问在线文档。

配置项目设置

1. 基本配置

在项目Admin页面可以配置：

• 项目描述和标签
• 默认文档版本
• 通知设置（构建失败提醒等）

2. 构建配置

通过.readthedocs.yaml文件可以精细控制构建过程：

version: 2

build:
  os: ubuntu-22.04
  tools:
    python: "3.8"

python:
  install:
    - requirements: docs/requirements.txt
    - method: pip
      path: .

sphinx:
  configuration: docs/source/conf.py
  fail_on_warning: true

formats:
  - pdf
  - epub

关键配置项说明：

• build.tools.python: 指定Python版本
• python.install: 定义依赖安装方式
• sphinx.configuration: 指定Sphinx配置文件路径
• formats: 定义额外输出格式（PDF/EPUB等）

高级功能

1. 多版本管理

Read the Docs支持文档版本控制：

• 自动从代码分支/tag创建文档版本
• 可设置默认版本（如stable或latest）
• 支持版本切换功能

2. Pull Request预览

启用PR构建功能后：

1. 创建文档修改的PR
2. Read the Docs会自动构建PR版本的文档
3. 提供预览链接供团队评审

3. 自定义域名

专业版用户可配置：

• 自定义文档域名（如docs.yourcompany.com）
• HTTPS证书自动管理

常见问题解决

构建失败排查

1. 查看构建日志中的错误信息
2. 常见问题：
   • 缺少依赖（添加requirements.txt）
   • Python版本不兼容（调整配置）
   • 文档语法错误（本地先测试构建）

文档更新不及时

1. 检查webhook是否配置正确
2. 确认代码推送到了正确的分支
3. 必要时手动触发构建

最佳实践建议

1. 文档与代码同仓库管理
2. 使用版本控制与语义化版本号
3. 为长期支持版本维护独立文档分支
4. 定期检查构建警告和错误
5. 为团队配置适当的通知设置

通过本教程，您应该已经掌握了使用Read the Docs托管技术文档的基本流程。该平台大大简化了文档的发布和维护工作，让开发者可以更专注于内容创作。