后端文档【免费下载链接】readthedocs.orgThe source code that powers readthedocs.org项目地址https://gitcode.com/gh_mirrors/re/readthedocs.org点击查看免费下载Read the Docs 会在每个新的拉取请求Pull Request上自动构建你的文档让你在合并前就能预览改动效果提前发现格式与显示问题。本文基于 readthedocs.org 官方文档与仓库源码系统讲解 Pull Request 预览的功能特性、开启配置、安全边界与常见故障排查帮助你把它接入自己的文档项目工作流。什么是 Pull Request 预览Read the Docs 为每一个新的 Pull Request 构建文档版本使评审者可以直接浏览改动后的文档页面而不是凭空推断代码改动对文档渲染的影响。预览构建在源码中被称为external builds在新建项目上默认开启你可以随时从项目控制台进入Settings → Pull request builds进行管理。从源码结构看Read the Docs 将 Pull Request 构建视为一种特殊类型的版本Version。在 readthedocs/builds/constants.py 中版本类型被定义为EXTERNAL external EXTERNAL_TEXT _(Pull request) VERSION_TYPES ( (BRANCH, BRANCH_TEXT), (TAG, TAG_TEXT), (UNKNOWN, UNKNOWN_TEXT), (EXTERNAL, EXTERNAL_TEXT), ) EXTERNAL_VERSION_STATE_OPEN open EXTERNAL_VERSION_STATE_CLOSED closed也就是说每次 PR 构建都会生成一个type EXTERNAL的临时版本对象其状态open/closed与 PR 的开合状态保持同步。Version模型通过is_external属性区分这类版本见 readthedocs/builds/models.py并通过explicit_name属性在界面上显示为类似#4 (PR)的命名见 readthedocs/builds/models.py。核心功能在 Pull Request 事件上触发构建当 Pull Request 被打开时Read the Docs 会为它创建并构建一个新版本当 PR 上推送新提交时该版本会被自动重新构建。这意味着文档预览始终与 PR 的最新代码状态保持一致。对应的触发开关定义在 readthedocs/projects/models.pyexternal_builds_enabled models.BooleanField( _(Build pull requests for this project), defaultTrue, help_text_( More information in a hrefhttps://docs.readthedocs.io/page/guides/autobuild-docs-for-pull-requests.htmlour docs/a. ), )该字段默认值为True与官方文档中新项目默认开启的描述一致。在构建执行端readthedocs/projects/tasks/builds.py 也会检查版本类型是否为EXTERNAL据此走外部版本的构建分支。构建状态上报你的项目在 Pull Request 上会显示一个构建状态检查check。构建运行期间状态持续更新构建完成后显示成功或失败。这样评审者在 PR 页面上就能直接看到文档构建结果无需跳转到 Read the Docs 控制台。该功能在源码中由各 Git 服务提供商的send_build_status方法实现。例如 readthedocs/oauth/services/github.py 会根据构建状态映射对应的 GitHub commit statuspending/success/failure并把target_url指向版本文档页或构建详情页def send_build_status(self, *, build, commit, status): # ... github_build_status SELECT_BUILD_STATUS[status][github] # ... if build.version.built: # Link to the docs target_url build.version.get_absolute_url() else: # Link to the build details page target_url build.get_full_url()带文件变更列表的构建概览Read the Docs 会在 Pull Request 上创建一个评论comment其中包含文档预览的链接以及当前 PR 与项目最新版本文档之间发生变更的文件列表。评审者可以据此快速定位改动涉及了哪些页面。需要注意的是该功能仅对通过 GitHub App 连接的项目可用。其开关定义在 readthedocs/projects/models.pyshow_build_overview_in_comment models.BooleanField( _(Show build overview in a comment), db_defaultTrue, help_text_( Show an overview of the build and files changed in a comment when a pull request is built. ), )关于构建概览的详细配置方法可参考 Visual diff 文档 中的 Show build overview in pull requests 一节。Pull Request 通知横幅你可以在预览页面顶部显示一条 Pull Request 通知提示读者他们正在查看的不是项目的正式版本。新项目的该通知默认关闭需要时可在Settings → Addons → Notifications中开启。该行为对应的数据库迁移可参见 readthedocs/projects/migrations/0160_notifications_show_on_external_help_text.py 与 readthedocs/projects/migrations/0161_addons_notifications_show_on_external_default_false.py。Visual diff 视觉对比Visual diff 通过在当前 Pull Request 与最新版本文档之间高亮差异直观展示将要产生的页面变化。在预览页面中按下键盘d键即可在 Visual diff 模式与普通 PR 预览模式之间来回切换。该功能与上一节的文件变更列表配合使用共同构成评审体验的核心。安全与隐私启用 Pull Request 预览意味着任何能在你的仓库上打开 Pull Request 的人都能触发你的文档构建。出于这一安全考量Read the Docs 将 PR 预览文档托管在与正式文档不同的域名下org.readthedocs.build和com.readthedocs.build隔离正式流量与外部构建流量。此外Pull Request 构建只能访问被标记为Public公开的环境变量。如果你的环境变量中包含私密信息务必不要将其标记为 Public。详见 环境变量文档 中的 Environment variables and build process 一节。隐私级别商业版在商业版Commercial上你可以将 Pull Request 预览设置为Public公开或Private私有如果你不是手动导入的项目且仓库是公开的PR 预览的隐私级别默认是PublicPublic预览对任何持有链接的人开放Private预览仅对有权访问该 Read the Docs 项目的用户开放。⚠️安全警告如果在一个公开仓库上将 PR 预览设为Private恶意用户可能利用正在阅读 PR 预览的用户会话访问只读 API类似 GitHub 安全公告 GHSA-pw32-ffxw-68rh 描述的风险。因此只有在能确保仓库中只有可信用户才能打开 Pull Request 时才应将 PR 预览设置为私有。隐私级别的判定逻辑在Version模型中有清晰体现readthedocs/builds/models.pyproperty def is_private(self): if self.is_external: return self.project.external_builds_privacy_level PRIVATE return self.privacy_level PRIVATE也就是说外部PR版本不走版本自身的privacy_level字段而是统一读取项目级字段external_builds_privacy_level定义于 readthedocs/projects/models.py。其默认值逻辑在 readthedocs/projects/models.py 附近当仓库为公开且非手动导入时默认设为PUBLIC。配置 Pull Request 构建以下操作步骤摘自官方指南 docs/user/guides/pull-requests.rst可直接对照执行。开启或关闭 PR 构建进入你的项目控制台dashboard打开Settings进入Pull request builds开启或关闭Build pull requests for this project选项点击Update保存提示在开启 PR 构建之前已打开的 Pull Request 不会自动触发新构建。向该 PR 推送一个新提交即可触发它的首次构建。注意此前通过 GitHub Workflow 调用readthedocs/actions来实现 PR 预览的旧方案已被废弃。如果你仍在使用该方式应移除相应配置。更改隐私级别进入项目控制台打开Settings → Pull request builds在Privacy level of builds from pull requests中选择你的选项点击Update保存隐私级别的工作方式与普通版本的版本状态一致。开启或关闭 PR 构建、更改隐私级别的界面逻辑可在 readthedocs/projects/views/private.py 与 readthedocs/projects/urls/private.py 中找到对应的视图与路由。配置前置条件你的 Read the Docs 项目需要连接到受支持的 Git 提供商仓库。目前 PR 预览仅支持 GitHub 和 GitLabBitbucket 暂不支持。如果你的项目使用的是 GitHub App 集成无需手动配置 Webhook。对于 GitLab 以及使用旧版 GitHub 集成的项目需要确保仓库 Webhook 配置为发送Pull Request 事件而不仅仅是 push 事件。限制说明PR 构建与普通构建享有相同的内存和时间限制。为缩短构建时间不构建 PDF 等附加格式。Read the Docs不会为 PR 构建建立搜索索引。因此 Addons 搜索与 Read the Docs Search API 对这些版本不会返回结果。PR 关闭或合并后构建出的文档会保留 90 天。构建概览评论仅对通过 GitHub App 连接的项目可用。PR 构建的产物存放在独立的external/存储路径下见 readthedocs/builds/models.py 的get_storage_path中if self.is_external: path f{EXTERNAL}/{media_type}与正式版本隔离管理。故障排查打开 Pull Request 后没有触发新构建最常见的原因是以 GitHub 为例你的 Read the Docs 项目没有连接到 GitHub 上对应的仓库。如果使用旧版 GitHub 集成请确认仓库 Webhook 配置为发送 pull_request 事件。你可以重新同步项目的 Webhook 集成来重配 Read the Docs Webhook进入项目管理员后台的Integrations选择对应提供商的 Webhook 集成按提示重新同步或新建 Webhook。也可能是你的 Read the Docs 账户与 Git 提供商账户断开了连接或需要重新连接。请进入用户名下拉菜单 → Settings → Connected Services重新连接账户。构建状态没有上报到 Git 提供商如果打开 PR 确实触发了构建但状态没有在 Git 提供商处更新说明你连接的账户可能权限过期或不足。请确认你已为个人或组织 GitHub 账户授予 Read the Docs GitHub OAuth App 的访问权限。小结Pull Request 预览是 Read the Docs 将文档即代码理念落到评审流程中的关键能力每次 PR 自动构建、状态回写到 PR 检查项、评论展示文件变更与预览链接配合 Visual diff 与安全隔离域名形成一套完整的文档评审闭环。理解其EXTERNAL版本模型与隐私级别设计readthedocs/builds/models.py、readthedocs/projects/models.py有助于你在自建或二次开发场景中正确配置这一特性。赞分享后端文档【免费下载链接】readthedocs.orgThe source code that powers readthedocs.org项目地址https://gitcode.com/gh_mirrors/re/readthedocs.org点击查看免费下载相关推荐Read the Docs 拉取请求构建Pull Request Builds配置指南预览、隐私与故障排查Read the Docs 拉取请求构建Pull Request Builds配置指南预览、隐私与故障排查 在 Read the Docsreadthe后端文档Chainlit 版本演进全解从 2.11 新特性到历史里程碑的完整技术盘点Chainlit 版本演进全解从 2.11 新特性到历史里程碑的完整技术盘点 Chainlit 是一款用于在几分钟内构建对话式 AI 应用的开源框架本篇后端文档使用 AWS CLI 创建 AWS CodeCommit 拉取请求Pull Request完整指南使用 AWS CLI 创建 AWS CodeCommit 拉取请求Pull Request完整指南 导读 本文基于 AWS CLI 官方示例文档讲解如何使开发工具云原生运维上一篇ComfyUI-GGUF完整指南如何在5分钟内实现AI模型显存优化下一篇GitHub汉化插件让全球代码社区触手可及的语言桥梁创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考