Read the Docs 用户指南：从零搭建、自动化构建与多版本托管的完整实战

后端文档【免费下载链接】readthedocs.orgThe source code that powers readthedocs.org项目地址https://gitcode.com/gh_mirrors/re/readthedocs.org点击查看免费下载Read the Docs 是一个以把文档当代码管理为核心理念的自动化文档托管平台你只需把文档源码与代码一起放进 Git 仓库推送代码时它会自动完成文档的构建、版本管理与托管。本指南以仓库中 docs/user/index.rst 这份用户入口文档为骨架系统梳理从项目接入、配置.readthedocs.yaml、理解构建流水线到多版本管理、子项目、自定义域名与商业特性的完整链路并结合 readthedocs.org 仓库源码给出底层实现依据帮助你真正把文档工程化。核心价值为什么把文档当作代码来管理docs/user/index.rst开篇即点明 Read the Docs 的设计哲学——文档应该和代码走同一条 Git 工作流。用团队已经熟悉的工具Git、Pull Request、分支与标签来维护文档收益是直接的文档永远与代码同步只要向 Git 推送代码Read the Docs 就会自动触发构建代码与文档始终保持一致。这也是 docs/user/index.rst 中Up to date documentation的核心承诺。每个版本都有对应文档仓库中的 tag 与 branch 会被映射为文档版本1.0 和 2.0 的文档可以同时在线读者看到的是与所用代码版本精确匹配的文档详见 docs/user/versions.rst。开源且以用户为中心Read the Docs 社区版Community免费托管开源项目文档商业版Business面向组织提供私有文档、SSO 等企业能力。对于第一次接触的读者官方建议按以下路径入手完整走一遍 教程导入一个 Sphinx 项目、配置并上线文档使用 MkDocs / Docusaurus 等工具的项目可参考 docs/user/intro/doctools.rst 快速上手从 示例项目 开始边看边学。从接入项目开始教程的核心流程要把一个项目托管到 Read the Docs完整流程以 教程 为准分为四步准备仓库在 GitHub 使用官方 tutorial-template 模板创建公开仓库如rtd-tutorial。模板仓库中已包含.readthedocs.yaml配置文件、README.rst、可安装的pyproject.toml元数据、示例源码lumache.py以及docs/目录下的 Sphinx 文档源。注册并连接账户通过 GitHub OAuth 注册 Read the Docs 账户。官方文档说明平台需要elevated permissions来安装 webhook、同步仓库等以保证接入流程顺畅见 docs/user/reference/git-integration.rst 的权限说明。导入项目在 Dashboard 点击Import a Project填写项目名称平台会用它生成唯一子域名、仓库 URL 与默认分支通常为main平台随即自动创建项目。检查首次构建项目创建后平台立即开始构建项目主页会显示Your documentation is building链接构建完成后即可点击View docs查看线上文档。从源码侧看导入项目后触发构建的整个生命周期在 readthedocs/builds/constants.py 中有明确建模构建状态机依次经过triggered → cloning → installing → building → uploading → finished另有cancelled终态见该文件中BUILD_STATE与BUILD_FINAL_STATES定义后续的跳过/取消构建章节会再次用到这套状态。用 Pull Request 预览文档接入 Git 集成后Pull Request 构建默认开启可在项目Settings → Pull request builds中管理。对 PR 修改提交后Git 提供方会出现 Read the Docs 检查项点击Details即可查看构建日志或直接预览该 PR 的文档。这是把文档评审融入代码评审流程的关键能力详细配置见 docs/user/pull-requests.rst。配置文件的完整参考.readthedocs.yaml 从模板到精调放对位置仓库根目录配置文件名固定为.readthedocs.yaml需放在仓库最顶层目录docs/user/config-file/index.rst。改动后提交并推送Read the Docs 会自动发现并使用。两个注意点如果配置文件在独立分支上新增可能需要先在 版本管理 中激活对应分支的版本如果配置文件是随 PR 提交的需确保 PR 构建 已开启构建才会真正使用它。官方模板Sphinx 与 MkDocs 两个起点仓库中提供两份可直接复制的官方模板Sphinx 项目docs/user/config-file/examples/sphinx/.readthedocs.yamlMkDocs 项目docs/user/config-file/examples/mkdocs/.readthedocs.yamlSphinx 模板的完整形态如下含注释说明# Read the Docs configuration file for Sphinx projects # Required version: 2 # Set the OS, Python version and other tools you might need build: os: ubuntu-24.04 tools: python: 3.12 # You can also specify other tool versions: # nodejs: 20 # rust: 1.70 # golang: 1.20 # Build documentation in the docs/ directory with Sphinx sphinx: configuration: docs/conf.py # You can configure Sphinx to use a different builder, for instance use the dirhtml builder for simpler URLs # builder: dirhtml # Fail on all warnings to avoid broken references # fail_on_warning: true # Optionally build your docs in additional formats such as PDF and ePub # formats: # - pdf # - epub # Optional but recommended, declare the Python requirements required # to build your documentation # python: # install: # - requirements: docs/requirements.txt模板中三类元素各有用途version: 2是必填项它告诉系统如何解析文件其余部分当前唯一受支持的版本就是 v2注释#开头解释各选项含义可原样保留被注释掉的示例选项是官方预置的常用配置样例按需取消注释即可启用。逐项精调核心键的语义与取值范围docs/user/config-file/index.rst只覆盖了高频键完整语义需要对照 docs/user/config-file/v2.rst 的官方参考下面按实际使用顺序展开build.os构建镜像指定构建所用的 Docker 基础镜像。官方模板使用基于最新 Ubuntu 的镜像镜像内包版本不会剧烈变动但会定期接收安全更新。若项目依赖旧版 Ubuntu 或需要新版特性应主动调整此键。参考中列出可选值ubuntu-22.04、ubuntu-24.04、ubuntu-26.04、ubuntu-lts-latest必填。注意ubuntu-lts-latest指向 Read the Docs 平台上最新的 Ubuntu LTS可能与官方最新 LTS 不一致升级时可能意外破坏不兼容的构建平台不支持任意自定义镜像。build.tools语言运行时版本控制构建环境中的多语言工具链版本至少需要指定一种工具build: os: ubuntu-24.04 tools: python: 3.13 nodejs: 22 rust: 1.82 golang: 1.23可用工具与取值以当前仓库文档为准工具可用版本节选说明python3.6~3.14、3最新 3.x 别名、latest另有miniconda3-*、miniforge3-*、mambaforge-*系列支持 CPython、Miniconda、Mamba 解释器nodejs14~26、latest前端文档构建常用ruby3.3、3.4、4.0、latestrust1.55~1.96、latestgolang1.17~1.26、latest每种工具的latest均指平台上提供的最新版本可能与官方最新版不同版本列表至少每六个月更新一次同样存在升级破坏构建的风险文档明确建议生产项目锁定具体版本而非使用latest。python.install依赖安装方式Read the Docs 默认用 pip 安装 Python 包也通过python.install支持uv。python.install是一个列表可按顺序声明多种安装方式详见 docs/user/config-file/v2.rst 的python.install小节python: install: - requirements: docs/requirements.txt - method: pip path: . extra_requirements: - docsrequirements指定 requirements 文件路径安装其中的包pathmethod: pip用pip install安装项目自身等效于pip install .[docs]python setup.py install已废弃setuptools方式也已弃用默认即pipmethod: uv使用 uv 安装依赖需配合command键command: sync→ 执行uv sync基于pyproject.toml如有uv.lock可用groups列表或all选择依赖组command: pip→ 执行uv pip install从requirements或本地path安装可用extras列表或all安装可选依赖约束sync不允许requirementspip必须提供requirements或path之一groups仅sync支持使用method: uv时python.install下只允许一个条目。condaConda 环境build: os: ubuntu-24.04 tools: python: mambaforge-22.9 conda: environment: environment.yml使用 Conda 时必须通过build.tools.python指定 Conda/Mamba 类解释器conda.environment指向仓库根目录相对的 environment 文件。使用 Miniconda3/Mambaforge/Miniforge3 时可在environment.yml中选定 Python 版本详见 docs/user/guides/conda.rst。sphinx/mkdocs构建器配置sphinx: builder: html configuration: conf.py fail_on_warning: truesphinx.builderhtml默认、dirhtml、singlehtml旧名htmldir已更名dirhtml但仍兼容sphinx.configurationconf.py相对路径必填sphinx.fail_on_warning等价于sphinx-build -W --keep-going有警告即以退出码 1 失败mkdocs.configurationmkdocs.yml相对路径必填mkdocs.fail_on_warning对应 MkDocs strict 模式。若需固定 Sphinx/MkDocs 具体版本官方推荐通过requirements.txt、environment.yml或extra_requirements锁定而不是依赖平台自动安装的最新版。formats附加输出格式formats: - epub - pdf类型为 list可选htmlzip、pdf、epub也可用all表示全部默认[]。两个重要限制目前仅 Sphinx 支持附加格式MkDocs 尚不支持 pdf/epub/htmlzip 输出如需可用build.jobs自定义命令生成离线格式PR 构建只生成 HTML其他格式消耗资源较多会在合并后构建。submodulesGit 子模块仅支持 Gitinclude与exclude不可同时使用submodules: include: - oneinclude/exclude可用all另有recursive默认 false控制递归拉取。详见 docs/user/guides/private-submodules.rst 了解私有子模块场景。search搜索配置search: ranking: api/v1/*: 2 ignore: - api/v0/*search.ranking用于调整页面在站内搜索中的权重值为整数可正可负search.ignore排除不希望被索引的页面路径详见 docs/user/config-file/v2.rst 的search小节。底层实现配置解析与严格校验配置文件并非写什么算什么readthedocs.org 在构建前会做严格校验。核心实现在 readthedocs/config/config.pyBuildConfigV2.validate()config.py是 v2 配置的校验入口内部按validate_formats、validate_conda、validate_build、validate_python、validate_sphinx、validate_mkdocs、validate_submodules、validate_search、validate_keys分项校验校验失败会抛出带ConfigError错误码的异常如config:build:jobs-and-commands表示build.jobs与build.commands冲突见 readthedocs/config/exceptions.py配置对象的数据结构用 pydantic 建模定义在 readthedocs/config/models.pyBuildJobs明确枚举了pre_checkout、post_checkout、pre_system_dependencies、post_system_dependencies、pre_create_environment、create_environment、post_create_environment、pre_install、install、post_install、pre_build、build、post_build全部钩子点且模型设置了extraforbid——任何未支持的键都会导致构建失败官方文档也明确任何不支持的配置项都会让构建失败这正是为了避免笔误并即时反馈。[docs/user/config-file/v2.rst](https://link.gitcode.com/i/df202b1f9bcdd02c9f052c3501362d59)还强调两点使用 v2 配置文件后Web 界面中的本地设置会被忽略一切以配置文件为准配置文件存放在 Git 中因此每个版本/分支可以拥有各自不同的构建配置这是多版本差异化构建的基础。构建流水线预定义任务与自定义扩展六步预定义任务一旦项目被添加且构建被触发Read the Docs 会在由build.os指定的 Docker 容器内执行一组预定义任务docs/user/builds.rst容器内可访问全部预定义与自定义环境变量checkout从 Git 仓库检出项目代码。商业版环境中还包含访问私有仓库所需的 SSH 部署密钥system_dependencies安装操作系统与运行时依赖包括语言版本由build.tools指定与apt包由build.apt_packages指定如libclang、cmake注意不支持 PPA 或自定义仓库且使用build.commands时该选项不可用官方建议尽量用 pip/conda 而非 apt 安装 Python 包create_environment创建隔离的 Python 环境virtualenv 或 conda 环境。该步骤仅在配置了sphinx或mkdocs键时执行install安装默认依赖与项目依赖包括requirements配置的依赖python.install可补充额外 Python 依赖。同样仅在配置了sphinx/mkdocs键时执行。官方强烈建议锁定所有构建所需版本以规避意外构建错误见 docs/user/guides/reproducible-builds.rstbuild针对formats声明的每种格式执行主构建命令Sphinx 或 MkDocsupload构建成功后把产物HTML、PDF 等上传到服务器并清除 CDN 缓存保证文档始终是最新的。自定义构建build.jobs 与 build.commands默认流水线无法覆盖所有场景.readthedocs.yaml提供两种自定义手段详见 docs/user/build-customization.rstbuild.jobs在预定义任务的钩子点插入/覆盖命令build: os: ubuntu-24.04 tools: python: 3.13 jobs: pre_create_environment: - echo Command run at pre_create_environment step post_build: - echo Command run at post_build step允许的键完整覆盖每个任务的前后钩子与任务本体post_checkout、pre_system_dependencies、post_system_dependencies、pre_create_environment、create_environment、post_create_environment、pre_install、post_install、pre_build、build、post_build。build.jobs.build还可按格式细分命令html/pdf/epub/htmlzip各格式产物需输出到$READTHEDOCS_OUTPUT对应子目录formats: [pdf, epub] build: os: ubuntu-24.04 tools: python: 3.13 jobs: build: html: - echo Building HTML - mkdir -p $READTHEDOCS_OUTPUT/html/ - echo Hello world! $READTHEDOCS_OUTPUT/html/index.html pdf: - echo Building PDF - mkdir -p $READTHEDOCS_OUTPUT/pdf/ - echo Hello world! $READTHEDOCS_OUTPUT/pdf/index.pdf若覆盖了pdf/epub/htmlzip步骤须把它们加入formats列表。配置了sphinx/mkdocs键时默认步骤会被执行、可被覆盖但要注意步骤间依赖默认install/build依赖create_environment创建的虚拟环境目录若两者都未配置平台只安装build.tools与build.apt_packages文档生成完全由你负责产物放入$READTHEDOCS_OUTPUT即可。build.commands完全接管构建build: os: ubuntu-24.04 tools: python: 3.13 commands: - pip install pelican - pelican --settings docs/pelicanconf.py --output $READTHEDOCS_OUTPUT/html/ docs/使用build.commands时所有预定义任务都不再执行且每条命令都在干净的 shell 环境中运行环境变量改动不跨命令持久化工作目录始终从 git 仓库开始。官方推荐优先使用build.jobs因为它在保留预定义任务的同时以结构化方式为每种格式定义命令且仍支持build.apt_packages。注意build.os与build.tools在两种方式下都是必填的。跳过、取消与自动禁用构建跳过Skipped从未触发的构建不占用构建时间、不进入构建历史。推荐用 自动化规则 的 webhook 过滤器实现例如只在docs/目录变更时构建、或在提交信息含[skip ci]时不构建取消Cancelled已触发但被中途停止的构建。三种取消机制管理员在构建详情页手动Cancel build检测到同一版本有新 push 时自动取消旧构建并启动新构建或通过build.jobs/build.commands自定义命令检查条件并以退出码 183取消构建退出码 0 则继续。取消后平台会向 Git 提供方通知构建成功避免 PR 出现失败检查自动禁用默认版本的构建若连续失败 25 次平台会自动禁用该项目构建以保护资源仅统计默认版本其他分支/标签/PR 不计入修复问题后需在项目设置中手动重新启用。构建资源限额构建有资源上限docs/user/builds.rst社区版为 15 分钟构建时间、7GB 内存、2 个并发构建、5GB 磁盘软限制商业版为 30 分钟构建时间可升级、7GB 内存可升级、并发数随套餐变化。社区版可按项目申请提高构建时间。多版本托管版本状态、slug 与工作流版本从哪来接入项目后仓库中所有 Git tag 与 branch 默认被创建为Inactive未激活且 Not hidden不隐藏的版本。初始设置时平台自动创建指向默认分支通常main的latest版本——它永远存在且是项目的默认版本。若仓库中存在符合 语义化版本可带v前缀的 tag/branch还会创建追踪最高稳定版本号的stable版本且排除 alpha、beta 等预发布版本若 tag 与 branch 并存tag 优先。配置了 Git 集成后每次 push 都会自动构建对应版本。版本状态矩阵每个版本有三维状态共同决定其可见性与可构建性维度状态含义Active / Inactive激活 / 未激活未激活版本内容会被删除且不能触发构建Hidden / Not hidden隐藏 / 不隐藏隐藏版本不在 flyout 菜单 与搜索结果中出现但持有链接者仍可访问并非私有隐藏版本会以Disallow: /path/to/version/写入默认 robots.txtPublic / Private公开 / 私有仅商业版可用私有版本对无权限者返回 404临时共享见 docs/user/commercial/sharing.rst版本在 push 提交或任意版本构建触发时自动同步若发现版本列表过期触发一次构建是最可靠的同步手段。版本 slug 的规则与陷阱版本 URL 标识符slug由分支/tag 名自动生成空格与/替换为-整体转小写若与既有 slug 冲突则追加_a、_b等后缀。slug 只能包含小写字母、数字、-、_与.。修改激活版本的 slug 会删除其旧文档并触发新构建旧 URL 会 404可用 用户自定义重定向 将旧版本重定向到新 URLlatest、stable这类由平台管理的版本 slug 不可修改。版本选择器中的排序也基于 slug改名可能改变读者看到的顺序。默认版本与版本化工作流访问文档根 URL如https://pip.readthedocs.io/会被重定向到默认版本默认latest常见配置改为stable。平台对版本有一组可调假设latest指向最新开发代码可通过 Default Branch 修改跟踪的分支tag 是符合 PEP 440 的快照最新语义化 tag 映射为stablebranch 被视为长生命周期分支如长期维护的2.1发布分支。禁用版本化可配置单版本项目URL 中将隐藏版本段。另外作为 Addons 的一部分平台会在非 stable 版本与 latest 版本上显示非稳定/最新开发版提示通知帮助读者识别文档版本状态项目管理员可在 Addons 中配置。托管进阶子项目、自定义域名、本地化与 URL 前缀子项目一个域名下聚合多个文档子项目docs/user/subprojects.rst让多个独立维护的文档项目共享同一站点、搜索索引与命名空间或自定义域名主项目example-project的文档位于https://example-project.readthedocs.io/en/latest/子项目example-project-plugin别名plugin则位于https://example-project.readthedocs.io/projects/plugin/en/latest/添加子项目后其原独立域名example-project-plugin.readthedocs.io会自动重定向到主项目路径下子项目自身不允许配置自定义域名始终从父项目域名提供服务各子项目保留独立的发布周期flyout 菜单会按当前查看的项目展示其自身版本与离线格式搜索聚合父项目搜索包含子项目结果可按子项目过滤搜索父项目v1版本时会包含子项目v1版本无v1版本时回退到默认版本。这是当前唯一跨项目共享搜索结果的方式兄弟子项目间暂不支持共享Show subprojects filter in search modal可在父项目Settings → Search中关闭商业版 Pro 及以上套餐可通过 docs/user/url-path-prefixes.rst 自定义或移除/projects/前缀子项目间跨项目引用可借助 intersphinx。自定义域名与 URL 路径前缀通过 docs/user/custom-domains.rst 可在自有域名下品牌化文档docs/user/url-path-prefixes.rst 允许调整版本 URL 中的/en/等语言路径前缀以及子项目的/projects/前缀商业版 Pro 起。结合 docs/user/localization.rst 的多语言翻译托管一套域名即可承载完整的国际化文档矩阵。为保证 SEO 一致性docs/user/canonical-urls.rst 说明了规范 URL 的处理方式docs/user/reference/cdn.rst 则解释了上传后 CDN 缓存刷新机制。维护与洞察重定向、安全日志与分析用户自定义重定向项目演进后旧 URL 需要保留跳转能力。docs/user/user-defined-redirects.rst 支持把旧 URL 重定向到新位置典型案例包括旧版本重定向到新版本docs/user/guides/redirects.rst 提供了常见重定向场景的逐步指南。流量分析与搜索分析洞察读者行为的两大利器Traffic Analyticsdocs/user/traffic-analytics.rst展示过去 30 天最常访问的页面与每日访问趋势不存储可识别访客身份的信息尊重隐私数据可一键 CSV 导出Search Analyticsdocs/user/search-analytics.rst展示读者最常搜索的查询词、每个查询返回的结果数与搜索次数可据此判断哪些文档区域难以被找到同样支持 CSV 导出。这两类数据都从项目页的Admin → Traffic Analytics / Search Analytics进入。安全日志与其他docs/user/security-log.rst 记录项目安全事件供审计docs/user/badges.rst 提供文档状态徽章用于嵌入 READMEdocs/user/explanation/documentation-structure.rst 从方法论层面解释为什么采用多页面文档结构是理解平台设计意图的延伸阅读。商业版能力与参考资源商业版docs/user/commercial/index.rst在社区版基础上提供组织级能力多团队权限管理organizations、SAML/Google 邮箱等单点登录single-sign-on、与承包商/客户安全共享私有文档sharing、按需订阅与配额subscriptions以及项目级隐私级别privacy-level。进阶参考索引完整 API 文档见 docs/user/api/index.rst变更记录见 docs/user/changelog.rst常见问题见 docs/user/faq.rst全部分场景 How-to 指南见 docs/user/guides/index.rst。开发者若希望深入平台本身可继续阅读 docs/dev/index.rst 中的设计文档与贡献指南或直接阅读 readthedocs/ 目录下的源码构建状态机在 readthedocs/builds/constants.py配置校验在 readthedocs/config/config.py。至此从创建账户、导入项目、配置.readthedocs.yaml、理解六步构建流水线到管理多版本、子项目与商业特性你已具备把文档工程化的完整工具箱文档与代码同仓库、同节奏、同版本剩下的就是保持文档如代码的习惯让 Read the Docs 持续替你自动构建与托管。赞分享后端文档【免费下载链接】readthedocs.orgThe source code that powers readthedocs.org项目地址https://gitcode.com/gh_mirrors/re/readthedocs.org点击查看免费下载相关推荐Read the Docs 自动化规则Automation Rules完整指南用 Git 事件驱动文档版本管理与构建Read the Docs 自动化规则Automation Rules完整指南用 Git 事件驱动文档版本管理与构建 自动化规则Automation R后端文档Read the Docs完全指南10分钟搭建专业文档托管平台在当今开源世界中 Read the Docs 已经成为文档托管的黄金标准为开发者提供了免费的文档托管服务。这个强大的文档托管平台支持 Sphinx、MkDo后端文档Read the Docs 用户 FAQ 实战指南构建、配置与多语言部署全解析Read the Docs 用户 FAQ 实战指南构建、配置与多语言部署全解析 本文是 readthedocs.org 开源仓库中 docs/user/faq后端文档上一篇JeecgBoot JimuReport多页PDF导出排版问题分析与解决下一篇QuickRecordermacOS上终极免费屏幕录制工具完整指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考