后端文档【免费下载链接】readthedocs.orgThe source code that powers readthedocs.org项目地址https://gitcode.com/gh_mirrors/re/readthedocs.org点击查看免费下载Read the Docs 本质上是一个持续文档部署Continuous Documentation Deployment平台每次你向 Git 仓库提交改动Read the Docs 都会通过 webhook 感知变更并自动重新构建文档。本文基于 docs/user/continuous-deployment.rst 展开结合仓库源码与关联指南系统讲解 webhook 触发链路、Docs as Code 工作流、自动化版本管理、PR 预览、跳过/取消构建与直接上传Direct Upload等能力帮助你把自己的文档发布流程完整接入 CI/CD。持续文档部署一次提交一次发布在 Read the Docs 的项目模型里文档与软件共用同一个 Git 仓库与同一条发布链路。每当你修改文档并提交到仓库Read the Docs 会通过配置在 Git 托管平台GitHub、GitLab、Bitbucket 等上的webhook收到通知随后执行以下步骤构建最新提交为触发构建的提交运行完整的构建流程详见 builds同步版本根据 Git 中最新 tag 与 branch 数据同步项目的 versions执行自动化规则运行项目的 automation rules自动取消同版本的正在运行构建如果同一版本正在构建则取消旧构建、以最新提交重新构建记录日志在集成Integration页面的 :guilabel:Recent Activity中追加一条日志。其中“自动取消同版本正在运行的构建”这一行为在源码层面对应构建生命周期中的取消机制Read the Docs 检测到某版本已有正在运行的构建时会取消它并基于最新 commit 启动新构建参见 docs/user/builds.rst 中 “Cancelling builds” 一节的 “Automatically” 描述。webhook 与 Integration 的匹配机制从源码结构看webhook 入口集中在 readthedocs/api/v2/urls.py它注册了多条路由webhook/github/project_slug/→GitHubWebhookViewwebhook/gitlab/project_slug/→GitLabWebhookViewwebhook/bitbucket/project_slug/→BitbucketWebhookViewwebhook/generic/project_slug/→APIWebhookViewwebhook/project_slug/integration_pk/→WebhookView也就是说每个 webhook 最终都会匹配到某个项目的 Integration 记录。Integration 模型定义在 readthedocs/integrations/models.py其中Integration是“入站 webhook 集成”的基础类而GitHubWebhook等子类通过integration_type_id标识具体类型如GITHUB_WEBHOOK并携带has_sync标记——这解释了为什么收到 webhook 后会触发版本同步集成对象本身声明了是否具备同步远程仓库的能力。文档即代码Docs as Code让文档进入评审与迭代闭环“文档即代码”Documentation as Code是本节核心方法论让文档的生命周期与软件项目完全一致即文档变更与源码变更进入同一条代码评审流程。收益非常明确自动化、短反馈循环文档改动被提交后立即触发构建与预览维护成本极低更多迭代因为反馈快团队更愿意反复修改文档文档的整体价值随之提升评审前置文档和源码在同一 PR 中被评审避免“文档滞后于功能”的典型问题。作为这条快速反馈循环的关键一环Read the Docs 提供pull request previews详见 pull-requests对每个新 PR 自动构建文档预览让评审者在合并前就能看到文档的实际渲染效果提前发现格式与展示问题。PR 预览的核心能力在 PR 事件上构建PR 打开时创建并构建新版本此后每次推送新 commit 都会重新构建构建状态上报PR 的构建状态会作为 checks 显示在 PR 上构建期间实时更新结束后显示成功/失败构建概览与变更文件列表在 PR 上创建评论包含文档预览链接以及当前 PR 与项目最新版本文档之间的 文件变更列表该能力仅对通过 GitHub App 连接的项目可用PR 通知可在预览页面顶部显示“这不是活跃版本”的通知新项目默认关闭可在 :guilabel:Settings→ :guilabel:Addons→ :guilabel:Notifications开启Visual diff按d键可在 Visual diff 与普通 PR 预览之间切换以视觉高亮方式呈现差异。安全注意事项PR 预览默认开启时任何能向你仓库发起 PR 的人都可能触发一次文档构建。因此 PR 预览被托管在与主文档不同的域名org.readthedocs.build与com.readthedocs.build且PR 构建只能访问标记为Public的环境变量。如果预览设为 Private务必确保只有受信任的用户能向你仓库提交 PR否则存在类似GHSA-pw32-ffxw-68rh的风险。手动配置 Git Provider Webhook对于 Read the Docs 未提供自动配置的 Git 托管平台需要手动创建 webhook 集成完整指南见 git-repo-manual。手动导入的仓库不支持回传 commit status如果依赖该能力应使用 git-integration 所述的方式自动配置。各平台的操作要点如下GitHub项目 :guilabel:Settings→ :guilabel:Webhooks→ :guilabel:Add webhook。Payload URL 使用 Read the Docs 项目 :guilabel:Admin→ :guilabel:Integrations页面上的集成 URL必要时补上https://前缀Content type 可选application/json或application/x-www-form-urlencodedSecret 填集成中的值事件选择 “Let me select individual events” 并勾选Branch or tag creation、Branch or tag deletion、Pull requests、Pushes。可在 GitHub 页面底部 :guilabel:Recent Deliveries验证Response 200 表示配置正确403 通常是 Payload URL 有误。GitLab:guilabel:Settings→ :guilabel:WebhooksURL 同上Secret token 填集成值默认保留Push events额外勾选Tag push events与Merge request events。Bitbucket:guilabel:Settings→ :guilabel:Webhooks→ :guilabel:Add webhookTriggers 勾选Repository pushSecret 填集成值。Gitea非官方支持但 Gitea 与 GitHub 载荷相同可创建 “GitHub webhook” 集成作为有效变通在 Gitea 实例上创建类型为 “Gitea” 的 webhook勾选Branch or tag creation、Branch or tag deletion、Push事件用 :guilabel:Delivery test验证最后回到 Read the Docs 确认警告消失且测试触发了构建。其他平台通过通用 webhook 支持见下文“通用 API 集成”。Payload 校验与集成管理所有集成创建时都会生成secret token用于验证 webhook 请求的合法性校验方式依各平台而定GitHub 使用其 webhook 签名方案、GitLab 使用 Secret token、Bitbucket 使用其安全 webhook 机制。手动添加集成的入口是 :guilabel:Admin→ :guilabel:Integrations→ :guilabel:Add integration集成 URL 形如https://app.readthedocs.org/api/v2/webhook/project-name/id/*把它填入各平台 webhook 配置即可。注意为 Gitea 手动创建 “GitHub webhook” 集成时Read the Docs 会显示“webhook 未正确配置”的警告当 Gitea 端配置完成并触发一次测试后警告会消失。通用 API 集成Generic API Integration对于不支持 webhook 的托管场景Read the Docs 还提供通用 API 端点用于触发项目构建对应源码中的APIWebhookView与WebhookView路由。它同样拥有可在 :guilabel:Integrations页找到的专属 URL且必须使用 token 认证——token 在集成详情页获取可作为表单数据或 JSON 数据传入。POST 参数参数说明默认值/必填性branches要触发构建的分支名可以是分支名数组或单个字符串默认latesttoken集成 token见 :guilabel:Admin→ :guilabel:Integrations必填default_branch仓库默认分支不带参数 clone 时检出的分支可选例如用 token1234构建项目example-project的dev分支$ curl \ --data branchesdevtoken1234default_branchmain \ https://app.readthedocs.org/api/v2/webhook/example-project/1/Python 等价实现import requests URL https://app.readthedocs.org/api/v2/webhook/example-project/1/ TOKEN 1234 response requests.post( URL, data{branches: dev, token: TOKEN, default_branch: main}, ) print(response.json())这类命令非常适合放进cron 定时任务或Git hook中调用。认证逻辑方面若使用集成 token系统会校验 token 是否有效且与给定项目匹配若以已认证用户发起请求则校验该用户是否为项目 owner。Webhook 排障调试 webhook每个集成webhook 或通用 API 端点的详情页都会保存 Read the Docs 与外部来源之间的 HTTP 交换记录可据此排查问题“Webhook activation failed. Make sure you have the necessary permissions”确认你的用户对仓库有权限GitHub 场景需检查是否已授权 Read the Docs 的 OAuth App 访问你的组织项目没有自动构建先在 Read the Docs 上查看集成收到的 payload。若无最近活动说明 Git 托管平台侧配置有问题若 Read the Docs 侧有 payload 记录则需检查对应 versions 是否配置为可正常构建。自动化版本管理让 Git 事件驱动文档发布Read the Docs 的版本概念直接映射 Git 实体版本就是 Git 的 tag 与 branch详见 versions。项目导入后所有 Git tag 与 branch 默认以Inactive 且 Not Hidden状态创建Read the Docs 自动创建指向仓库默认分支通常是main的latest版本它始终存在且是项目默认版本若存在符合语义化版本可带v前缀的 tag 或 branch还会自动创建stable版本跟踪最大的稳定语义化版本号排除 alpha、beta 等预发布版本若有多个候选tag 优先于 branch参与比较配置了 git-integration 后每次 push commit 都会自动构建对应版本。版本状态分为三组维度Active/Inactive激活的文档可见、可构建未激活版本的内容会被删除且不可构建、Hidden/Not hidden隐藏版本不显示在 flyout 菜单、不出现在搜索结果中但仍可通过链接访问并会被默认 robots.txt 以Disallow: /path/to/version/记录、以及仅商业版可用的Public/Private私有版本对无权限用户返回 404临时分享可参考 sharing。版本同步会在“push commit 且配置了 Git 集成”或“任意版本触发构建”时自动发生如果发现版本列表过期触发一次构建是重新同步的最可靠手段。Automation Rules把版本化决策写进规则automation rules 允许维护者对新的 branch、tag 与 PR 自动执行动作把版本控制与构建决策完全交给 Git 仓库不在 Read the Docs 上重复劳动。收到 webhook 后Read the Docs 会创建或更新与 Git tag/branch/PR 对应的版本然后按页面上的顺序逐条评估所有已启用的规则。每条规则包含按顺序检查的三组条件版本类型规则所选类型tag / branch / pull request可多选版本名称匹配版本名——预置Any version全部匹配与SemVer versions符合语义化版本可带v前缀也可使用 Python 正则的Custom matchWebhook filters可选基于 webhook 事件数据过滤——Changed files*匹配一切含斜杠、?匹配单字符、[seq]匹配字符集如docs/*、*.md、.readthedocs.yaml多行多模式任一文件命中任一模式即匹配、Commit message用正则匹配 push 的提交信息或 PR 头 commit、Pull request labels正则匹配 PR 标签仅 PR 事件有效。配置多个过滤器时全部必须匹配。Webhook filters 仅对通过 GitHub App 连接的项目可用。当所有条件匹配规则的动作被执行。动作分两类版本动作激活版本Activate version、隐藏版本Hide version未激活则先激活并构建、设为公开/私有、设为默认版本Set version as default同时激活并构建、删除版本Delete version允许在 branch/tag 删除时删除活跃版本。注意默认版本即使匹配规则也不会被删除若版本遵循 PEP 440 且高于当前 stable激活时 stable 会自动更新。构建动作Trigger build for version——当项目存在至少一条启用该动作的规则时构建会被这些规则“门控gated”若没有构建规则匹配该 webhook 事件则不触发构建未配置任何构建规则时每次 push/PR 仍照常触发构建。因此该动作通常与 Webhook filters 配合实现“仅相关内容变更时才构建”。常用规则示例可直接在 :guilabel:Automation Rules页面配置目标版本类型匹配动作激活所有新 tagTagAny versionActivate version激活1.x分支Branch自定义^1\.\d$Activate version分支删除时删除活跃版本BranchAny versionDelete version后缀-stable/-release的 tag 设为默认Tag自定义-(stable\|release)$Set version as default激活v/V开头的 tag 与 branchTag、Branch自定义^[vV]Activate version仅文档变更时构建Tag、Branch、PRAny version Changed filesdocs/*、.readthedocs.yaml、requirements/docs.txtTrigger build for version跳过含[skip ci]的提交Tag、Branch、PR自定义提交信息正则^(?!.*\[skip ci\]).*Trigger build for version仅构建带documentation标签的 PRPRPR 标签正则^documentation$Trigger build for version发布周期对齐一次 release一份文档版本通过上述机制项目的发布周期可以与文档完全对齐软件发布新版本时通常会在 Git 仓库打版本 tag该 Git 事件可被配置为自动构建并发布新的 文档版本版本化方案可作为自动化过程的一部分进行配置。无论选择全自动还是手动控制Read the Docs 都会保存版本历史让用户能访问存档的旧版本文档版本配置最终通过flyout menu详见 flyout-menu呈现并可通过 addons 集成到文档中——例如非 stable 版本上的“过时文档”通知、latest 版本上的“开发版本”通知等。控制构建开销跳过、取消与自动禁用在持续部署流水线中并非每次提交都值得构建。builds 文档给出了三类控制手段跳过构建Skipped从未被触发的构建不会出现在构建历史、不消耗构建时间。推荐做法是用automation rules Webhook filters只在相关文件变更时构建如仅docs/目录被修改或排除含[skip ci]的提交。取消构建Cancelled已触发但被提前停止的构建会以Cancelled状态留在构建历史中。三种取消机制管理员在构建详情页点击 :guilabel:Cancel buildRead the Docs 检测到某版本正在构建时收到新 push自动取消旧构建并启动新构建或通过自定义命令build.jobs/build.commands见 build-customization以退出码183取消构建退出码 0 则继续。自动禁用Automatic disabling当项目默认版本连续 25 次构建失败时Read the Docs 会自动禁用该项目的构建以节约资源、改善队列时间该限制仅统计默认版本其他版本分支、tag、PR不计入。被禁用后需在项目设置中重新启用并先修复根本问题。不依赖托管构建Direct Upload 自有流水线如果你的文档工具不被 Read the Docs 构建流程支持、构建需要自有环境的工具/密钥/资源或你已在 CI 中构建文档并想复用结果可使用Direct Upload详见 direct-upload目前为 beta 功能需联系支持开启。上传后的文档保留全部托管能力versions、PR 预览、服务端搜索、Addons、自定义域名、可下载格式等。前置条件项目已开启 Direct Upload持有项目管理员账号的 API token存为 CI 的 secret。GitHub Actions 示例.github/workflows/docs.yamlname: Docs on: push: branches: [main] tags: [v*] pull_request: jobs: docs: runs-on: ubuntu-latest # 来自 fork 的 PR 无法访问 secrets不要用 pull_request_target 绕过 # 那会让 PR 的代码带着你的 token 运行。 if: github.event.pull_request.head.repo.full_name github.repository steps: - uses: actions/checkoutv5 # 用你已有的工具构建文档以 Sphinx 为例 # # - uses: actions/setup-pythonv6 # with: # python-version: 3.14 # - run: pip install -r docs/requirements.txt # - run: sphinx-build -b html docs/ _build/html - uses: readthedocs/upload-actionv1 with: token: ${{ secrets.READTHEDOCS_TOKEN }} project-slug: your-project-slug html: _build/htmlworkflow 从名为READTHEDOCS_TOKEN的 secret 读取 token在 :menuselection:Settings -- Secrets and variables -- Actions中添加。upload action 会根据 workflow 事件自动识别分支/tag/PRpush 到main更新main版本新 tag 创建新版本PR 则创建 PR 预览。任意 CI 环境upload action 本质上是readthedocs-uploadCLI 的薄封装要求 Python 3.10从READTHEDOCS_TOKEN环境变量读取 token$ export READTHEDOCS_TOKENtoken $ uvx --from readthedocs-upload readthedocs upload \ --project-slug your-project-slug \ --html _build/html也可以pip install readthedocs-upload获得readthedocs命令。GitHub Actions 之外客户端从本地 Git checkout 推断版本其他 CI 需显式传参$ readthedocs upload \ --project-slug your-project-slug \ --html _build/html \ --version-name branch, tag or pull request number \ --version-type branch, tag or external \ --commit full commit hashPDF、ePub、zip 等离线格式可选上传--pdf/--epub分别指向单文件会像普通下载格式一样显示在 flyout menu。限制上传压缩包最大 1 GB、上传须在 30 分钟内完成、单项目同时最多 50 个进行中的上传。结语把文档发布纳入持续交付主航道综合来看Read the Docs 的持续部署模型围绕三条互补路径展开Webhook 驱动的自动构建提交即构建配合 Automation Rules 精确控制触发条件、版本化发布tag/branch/PR 映射为文档版本发布周期与文档完全对齐、以及Direct Upload在自有 CI 中构建、向 Read the Docs 上传成品。无论走哪条路径docs/user/continuous-deployment.rst所强调的核心原则始终不变文档的生命周期与软件一致文档变更与源码同评审、同发布、同迭代。延伸阅读仓库内可直接查阅builds构建流程、跳过/取消/自动禁用机制versions版本状态、slug 规则与版本化工作流automation-rules自动化规则完整语法与示例pull-requestsPR 预览功能与安全边界git-repo-manual手动配置各平台 webhook 的逐步操作direct-upload自有 CI 构建 上传的完整配置git-integrationGit 集成与 commit status 上报flyout-menu 与 addons版本切换菜单与文档内通知组件赞分享后端文档【免费下载链接】readthedocs.orgThe source code that powers readthedocs.org项目地址https://gitcode.com/gh_mirrors/re/readthedocs.org点击查看免费下载相关推荐使用 Read the Docs Automation Rules 自动化管理文档版本使用 Read the Docs Automation Rules 自动化管理文档版本 本文以 readthedocs.org 仓库中 docs/user/gu后端文档如何为TensorFlow创建可插拔设备插件完整开发指南如何为TensorFlow创建可插拔设备插件完整开发指南 TensorFlow的可插拔设备架构允许开发者为TensorFlow添加对新硬件设备的支持而无需修人工智能AI 应用Agent 记忆MCP 服务Kingfisher规则库管理950内置规则的分类与使用Kingfisher规则库管理950内置规则的分类与使用 Kingfisher是一款功能强大的密钥检测工具提供950内置规则帮助用户发现并管理代码中的敏上一篇5分钟掌握BOTW存档编辑器塞尔达传说旷野之息修改完全指南下一篇ComfyUI-Impact-PackAI图像智能增强的终极解决方案创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考