后端文档【免费下载链接】readthedocs.orgThe source code that powers readthedocs.org项目地址https://gitcode.com/gh_mirrors/re/readthedocs.org点击查看免费下载本篇指南完整讲解如何借助 Read the Docs 社区版Community把一个公开文档项目托管上线从 GitHub 模板仓库的创建、账号授权与项目导入到首次构建的验证、.readthedocs.yaml配置文件逐项精调Python 版本、依赖安装、fail-on-warning、PDF/EPUB 离线格式再到多版本latest/stable管理与流量/搜索分析。读完你将掌握一套可复制的「代码仓库 → 文档托管 → 持续构建」完整实战流程。教程概览你将完成什么本教程围绕一个虚构的 Python 库Lumache/lumake/一个为厨师和美食爱好者生成食谱的库展开全程不需要任何 Sphinx 使用经验。整条主线包含三步导入一个基于 GitHub 仓库的 Sphinx 项目到 Read the Docs定制项目的构建配置探索其他实用的 Read the Docs 功能。前置条件很简单需要一个 GitHub 账号免费注册。教程最终会让你走完「Fork 仓库 → 连接 Read the Docs → 构建 HTML 文档 → 定制构建流程 → 新增文档版本 → 浏览项目分析」这一整条链路这也是每个文档项目上线时都会经历的标准路径。说明本教程面向 Read the Docs 社区版免费托管服务。社区版与商业版Read the Docs Business在隐私级别、单点登录、私有仓库支持等能力上存在差异详见官方定价页的 Community 与 Business 对比。第一步在 GitHub 上准备仓库从官方模板创建仓库教程提供了一个官方模板仓库 readthedocs/tutorial-template。登录 GitHub 后打开该模板点击绿色的Use this template按钮再点击Create a new Repository在新页面中填写三个关键字段字段建议取值说明Owner默认或你自己的账号教程项目建议放在自己的账号下Repository name例如rtd-tutorial取一个好记且贴切的名字VisibilityPublic必须社区版面向公开文档项目务必选公开而非私有点击绿色Create repository按钮后你就拥有了一个包含以下文件的公开仓库.readthedocs.yamlRead the Docs 构建配置文件必选控制整个构建流程README.rst仓库描述文件pyproject.tomlPython 项目元数据使仓库可被安装便于文档构建时自动从源码生成 API 文档lumache.py虚构 Python 库的源码docs/全部文档源码目录内含 Sphinx 配置docs/source/conf.py与根文档docs/source/index.rst。这个模板结构本身就是一个值得学习的文档工程样板文档源码与代码同仓docs-first 布局、用 pyproject.toml 描述依赖、用.readthedocs.yaml声明构建规则。后续所有配置实验都在这个仓库上进行。创建 Read the Docs 账号进入 Sign Up 页面选择Sign up with GitHub选项在授权页点击绿色Authorize readthedocs按钮即可完成 OAuth 登录。为什么要授予这些权限Read the Docs 需要「提升权限」才能替你完成一些自动化操作例如安装 webhookwebhook 用于在 GitHub 上推送代码、创建分支/标签时自动触发文档构建。更多权限细节可参阅 连接账号的权限说明。授权后你会被重定向回 Read the Docs 确认邮箱与用户名点击Sign Up »按钮即完成注册并进入你的 dashboard仪表盘。随后根据邮件中的链接验证邮箱地址账号就绪可以创建第一个项目了。第二步把项目导入 Read the Docs导入并填写项目信息登录仪表盘后点击Import a Project按钮在仓库列表右侧点击rtd-tutorial旁的按钮如果列表为空点击刷新按钮重新同步仓库列表。随后填写项目详情字段建议取值说明Name建议{你的用户名}-rtd-tutorial项目名会用于生成每个项目唯一的子域名前缀用户名可避免冲突Repository URL保留自动填充值即文档源码所在的仓库地址Default branch保留main项目默认分支名点击Next按钮项目即创建成功并跳转到 项目主页project home。导入的那一刻Read the Docs 就会自动开始第一次构建——这也是它与普通静态站点托管最大的区别构建、发布、持续集成全部自动完成。查看首次构建日志创建项目后Read the Docs 会立刻开始构建文档。在项目主页点击Your documentation is building链接即可进入构建详情页如果构建尚未完成你会看到「Installing」或「Building」旁的加载动画构建完成后出现绿色的Build completed标识同时展示完成时间、耗时和生成文档的链接。点击View docs即可打开你的 HTML 文档并在线浏览。从源码实现看一个完整构建会依次经历triggered → cloning → installing → building → uploading → finished这些内部状态定义于 readthedocs/builds/constants.pyfinished与cancelled属于最终状态。这意味着你在界面上看到的「构建中」背后实际是克隆代码、创建虚拟环境、安装依赖、执行 Sphinx、上传产物的完整流水线。顺带说明广告是 Read the Docs 的主要收入来源之一其 EthicalAds 网络尊重隐私、不做用户画像投放并尽可能保持克制。若你没有看到广告可能是浏览器广告拦截器导致的详见 广告拦截说明。第三步配置项目基础信息在项目主页点击⚙ Admin按钮进入设置页本步完成三件事更新项目描述添加文案Lumache (/lumake/) is a Python library for cooks and food lovers that creates recipes mixing random ingredients.设置项目主页为https://world.openfoodfacts.org/并添加公开项目标签food, python配置构建失败通知点击左侧Email Notifications链接添加你的邮箱地址并点击Add按钮——这样任何一次构建失败都会第一时间邮件通知你。第四步从 Pull Request 触发构建Read the Docs 支持 从 GitHub Pull Request 触发构建 并预览变更后的文档。新项目默认启用该功能可在Settings → Pull request builds下确认。动手体验这个流程在 GitHub 仓库中找到docs/source/index.rst点击右上角「Edit this file」铅笔图标打开网页编辑器在文件中加入一行Lumache hosts its documentation on Read the Docs.填写合适的提交信息选择「为此提交新建分支并创建 Pull Request」选项点击绿色Propose changes按钮打开新的 Pull Request 页面再点击Create pull request按钮。打开 Pull Request 后一个 Read the Docs 检查项会出现表明它正在为该 PR 构建文档。点击Details链接构建期间打开的是构建日志构建完成后则直接打开该 PR 的文档预览。这样每次代码评审时文档变更都能同步预览是文档驱动开发工作流的关键一环。第五步用.readthedocs.yaml定制构建项目主页 Admin 标签页里是全局性的站点配置而构建过程配置全部放在 Git 仓库根目录的.readthedocs.yaml配置文件 中。配置文件随 Git 版本管理因此每个分支/版本都可以有不同的构建配置这也是多版本文档的基础。下面按教程顺序依次完成四个配置实验。实验一切换 Python 版本默认情况下构建使用最新的 Python 版本。若要改用 Python 3.8编辑.readthedocs.yamlversion: 2 build: os: ubuntu-22.04 tools: python: 3.8 python: install: - requirements: docs/requirements.txt sphinx: configuration: docs/source/conf.py各键的用途如下version必填声明 配置文件 v2 版本build.os必填指定构建文档所用的 Docker 基础镜像如ubuntu-22.04、ubuntu-24.04、ubuntu-lts-latest可参考 build.os 选项build.tools.python指定 Python 解释器版本除 CPython 外还支持 miniconda/mamba 系列python.install.requirements指定要安装的 Python 依赖。提交这些改动后回到项目主页进入Builds页面打开刚启动的新构建。你会注意到日志里有一行python -mvirtualenv点击展开可以看到完整输出其中明确写着使用的是 Python 3.8.63.8 系列的最新版本来创建虚拟环境。实验二让构建警告变得可见此时浏览 HTML 文档你会发现首页正常但 API 章节是空的——这是 Sphinx 的常见问题原因写在构建日志里。在之前的构建页面点击右上角View raw以纯文本打开构建日志能看到多条警告WARNING: [autosummary] failed to import lumache: no module named lumache ... WARNING: autodoc: failed to import function get_random_ingredients from module lumache; the following exception was raised: No module named lumache WARNING: autodoc: failed to import exception InvalidKindError from module lumache; the following exception was raised: No module named lumache要让这些警告不再被淹没在配置文件中加上sphinx.fail_on_warning选项version: 2 build: os: ubuntu-22.04 tools: python: 3.8 python: install: - requirements: docs/requirements.txt sphinx: configuration: docs/source/conf.py fail_on_warning: true提交后回到Builds页面你会看到一个Failed状态的构建——这正是期望的结果配置了 fail-on-warning 后任何 Sphinx 警告都会导致构建失败。底层实现上该选项对应 Sphinx 的-W--keep-going参数构建进程遇到警告即返回退出码 1见 sphinx.fail_on_warning 文档。警告被「放大」成失败后你就有动力去逐一修复它们了。实验三安装 Python 依赖autosummary与autodoc之所以导入lumache失败是因为lumache模块根本没有被安装。解决办法是在配置里声明安装需求python: install: - requirements: docs/requirements.txt # Install our python package before building the docs - method: pip path: .这样 Read the Docs 会在 Sphinx 构建前先把项目代码安装进虚拟环境构建随即顺利完成。回到 HTML 文档的 API 页面你就能看到lumache的模块摘要了。从配置解析源码看python.install支持三类条目见 readthedocs/config/config.py 的validate_python_installrequirements 文件安装requirements: 路径、路径安装method: pip|setuptools|uvpath:可附加extra_requirements、以及uv 安装method: uvcommand: sync|pip。其中extra_requirements仅当method为pip时允许且 uv 模式目前只允许python.install下存在一条记录。换言之这份 YAML 背后有严格的 schema 校验——任何不支持的键都会直接导致构建失败validate_keys会检查多余键。实验四启用 PDF 与 EPUB 离线格式Sphinx 除 HTML 外还能构建 PDF、EPUB 等格式方便用户离线阅读。在配置中加入formatssphinx: configuration: docs/source/conf.py fail_on_warning: true formats: - pdf - epub改动生效后PDF 和 EPUB 下载入口会同时出现在项目主页的Downloads区域以及 flyout 菜单 中。关于formats的几个要点可参考 formats 配置参考合法取值是htmlzip、pdf、epub也可用all表示全部目前仅 Sphinx 支持额外格式MkDocs 尚不支持可改用自定义构建命令生成另外Pull Request 构建只生成 HTML 格式其余格式消耗资源较大会在合并后构建。第六步文档版本管理Read the Docs 支持像管理代码版本一样管理 文档的多个版本。默认情况下它会创建一个指向 VCS 默认分支本教程即main的latest版本——这就是你的文档 URL 中总是包含/latest/的原因。创建新版本1.0.xRead the Docs 会自动从符合版本号规则如1.0、2.0.3、4.x的 GitHub 分支和标签创建文档版本详见 版本化工作流。要创建1.0版本在 GitHub 仓库点击分支选择器输入1.0.x点击Create branch: 1.0.x from main回到项目主页点击Versions按钮在Active Versions下会看到两个条目latest版本指向main分支新的stable版本指向origin/1.0.x分支。创建分支的瞬间Read the Docs 就自动创建了一个指向它的特殊版本stable构建完成后它会出现在 flyout 菜单中。把stable设为默认版本如果不希望用户访问文档根 URL 时看到latest可以把默认版本改为stable在项目主页⚙ Admin → Settings中于Default version*下拉框选择stable点击底部Save保存。此后用户访问根 URL 将看到stable文档。激活/隐藏版本当前latest和stable都处于active对用户可见、可触发新构建状态同时 Read the Docs 还创建了一个inactive的1.0.x版本它永远指向仓库的1.0.x分支。要激活它在项目主页进入Versions在Activate a version下找到1.0.x并点击Activate按钮在激活页面中只勾选Active复选框不勾Hidden点击Save。更多关于 版本状态hidden 等 的细节可查阅文档。从实现看latest与stable是保留版本名NON_REPOSITORY_VERSIONS见 readthedocs/builds/constants.py它们并不对应仓库中的真实分支/标签。排序时latest和stable会被特殊对待comparable_version赋予它们极高的排序权重仓库分支/标签的稳定版本则由 readthedocs/projects/version_handling.py 的determine_stable_version根据版本号排序选出优先标签、排除预发布版本。同时系统会校验仓库中不允许出现重名的分支与标签避免与保留版本名冲突见 readthedocs/projects/tasks/mixins.py 的validate_duplicate_reserved_versions。第七步获取项目洞察Analytics项目上线后你自然会关心读者如何使用文档哪些页面访问量最高哪些搜索词被最频繁使用读者是否找到了他们想要的内容Read the Docs 提供流量分析与搜索分析两套工具来回答这些问题。流量分析Traffic Analytics流量分析视图以简洁的方式呈现读者如何浏览你的文档并且通过不存储可识别身份的信息来尊重访问者隐私。页面展示过去 30 天被访问最多的文档页面以及同期每日访问量的可视化图表。查看方法回到项目主页点击⚙ Admin按钮再进入Traffic Analytics区块即可看到按访问量降序排列的页面列表和可视化图表。如需深入分析滚动到页面底部点击Download all data按钮即可把整份数据以 CSV 格式下载到本地。搜索分析Search Analytics搜索分析 展示读者在文档中搜索的关键词帮助你判断应该聚焦哪些内容或者哪些部分让读者感到困惑、难以找到。为了在项目上制造一些真实的搜索统计数据打开 HTML 文档在左侧的 Sphinx 搜索框中输入ingredients按回车你会被重定向到搜索结果页其中显示两条结果回到项目⚙ Admin → Search Analytics即可看到一张表包含被搜索最多的查询包括你刚输入的ingredients、每个查询返回了多少条结果、以及被搜索了多少次查询表下方还有过去 30 天每日搜索次数的可视化。与流量分析一样点击Download all data按钮可以 CSV 格式下载完整数据集。下一步继续深入恭喜你完成了整个教程你已经完成了Fork GitHub 仓库 → 连接 Read the Docs → 构建 HTML 文档 → 定制构建流程 → 新增文档版本 → 浏览项目分析。接下来可以从这些方向继续探索了解平台的完整 功能清单学习 Sphinx 教程 或 MkDocs 用户指南了解其他文档生成器查看 Read the Docs 示例项目查阅 操作指南 完成具体任务了解 商业版服务 中的私有项目支持与企业特性加入 Write the Docs 全球文档工作者社区并参与 Read the Docs 本身的 贡献指南。Happy documenting!赞分享后端文档【免费下载链接】readthedocs.orgThe source code that powers readthedocs.org项目地址https://gitcode.com/gh_mirrors/re/readthedocs.org点击查看免费下载相关推荐Read the Docs 文档托管平台使用教程Read the Docs 文档托管平台使用教程 什么是Read the Docs Read the Docs 是一个开源的文档托管平台专门为技术文档提供自后端文档如何使用Read the Docs文档自动化托管的终极指南如何使用Read the Docs文档自动化托管的终极指南 Read the Docs是一个强大的文档自动化托管平台能够帮助开发者轻松构建、托管和维护项目文后端文档Read the Docs 项目文档添加指南从零开始部署技术文档Read the Docs 项目文档添加指南从零开始部署技术文档 前言 作为技术文档托管平台Read the Docs 为开发者提供了便捷的文档托管和构建服后端文档上一篇Midori浏览器轻量高效的WebKit内核浏览器深度评测下一篇PlaidML版本管理指南从master分支到plaidml-v1的平滑过渡创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考