后端文档【免费下载链接】readthedocs.orgThe source code that powers readthedocs.org项目地址https://gitcode.com/gh_mirrors/re/readthedocs.org点击查看免费下载当你在项目中弃用一个功能时往往也需要同步处理它的文档既希望用户不再阅读这些内容又不想让保存了旧链接的用户撞上 404。Read the Docs 提供了一套渐进式、非破坏性的内容弃用方法——从隐藏整个版本、给页面降权到建立重定向每一步都可以在保持旧链接可用的情况下逐步推进。本文基于 docs/user/guides/deprecating-content.rst 展开并结合仓库源码说明底层实现读完你将掌握一套可落地的内容弃用方案。为什么直接删除不是好方案弃用内容听起来就像删除它一样简单但直接删除会带来两个问题破坏已有链接用户、外部站点和搜索索引中可能保存了大量指向该页面的链接删除后这些链接全部变成 404体验非常糟糕内容也许不该彻底消失你未必想让旧内容完全不可访问可能只是希望它不显眼、不出现在搜索结果中。Read the Docs 的思路是分阶段推进先用隐藏/降权让旧内容淡出一段时间后再用重定向接管旧链接。这个策略与 docs/user/user-defined-redirects.rst 中不管理 URL 结构用户迟早会遇到 404的警告一脉相承。处理 URL 结构、重命名和删除内容的更多最佳实践可参考 docs/user/guides/best-practice/links.rst。弃用整个版本隐藏 Version如果你的项目有多个版本文档也应当跟着版本化。假设你有以下三个版本希望弃用 v1https://project.readthedocs.io/en/v1/https://project.readthedocs.io/en/v2/https://project.readthedocs.io/en/v3/对这种场景可以用隐藏版本Hidden version的方式处理。隐藏版本的效果隐藏版本不会出现在文档的版本菜单flyout menu中隐藏版本会被写入自动生成的robots.txt以阻止搜索引擎展示该版本的搜索结果用户仍然可以通过直链访问隐藏版本的文档隐藏不等于私有项目 Dashboard 中依然可以看到所有版本。隐藏版本的完整状态定义见 docs/user/versions.rst 的 Version states 一节Active / InactiveInactive 版本的文档内容会被删除且无法触发构建Hidden / Not hiddenNot hidden 版本会出现在 flyout menu 和搜索结果中Hidden 版本两者都不出现但任何拿到链接的用户仍可访问——隐藏适合不再支持但不想移除文档或尚未准备好发布的场景Public / Private仅商业版Private 版本对无权限用户返回 404。操作步骤进入项目点击VersionsEdit勾选Hidden选项即可。隐藏版本的robots.txt行为在源码中有明确实现在 readthedocs/proxito/views/serve.py 的_get_hidden_paths中会筛选出所有hiddenTrue的公开版本并通过Resolver.resolve_path计算出它们的绝对路径随后在默认robots.txt中以Disallow: /path/to/version/的形式列出。这与 docs/user/reference/robots.rst 中默认 robots.txt 会隐藏设置为 Hidden 的版本的描述一致。版本弃用与 semver 联动如果你的版本号遵循 semver 规范还可以为项目开启version warning notifications版本警告通知选项凡是低于 stable 版本的文档页面上都会出现一条横幅提示用户当前版本已过时并引导他们跳转到 stable 版本。该通知由 Read the Docs Addons 提供具体触发逻辑见 docs/user/versions.rst 的 Version warning notifications 一节当展示的不是stable版本且存在stable版本时显示非稳定版通知当展示latest且存在未隐藏的活跃stable版本时显示最新版通知。从源码看Read the Docs 会基于packaging与bumpver解析版本号以确定stablereadthedocs/projects/version_handling.py 中的determine_stable_version会先按版本号降序排序剔除预发布版本pre-release并优先选择 Git tag 而非分支作为 stable 版本。弃用单个页面页内警告 搜索降权并非每次弃用都涉及整个版本有时你只想弃用某些页面。例如你的文档包含两套 API 文档现在要弃用 v1https://project.readthedocs.io/en/latest/api/v1.htmlhttps://project.readthedocs.io/en/latest/api/v2.html第一步在页面顶部加警告最简单的方式是在页面顶部添加一条警告warning告诉访问者该页面已弃用。但注意这只提醒了直接访问页面的用户并不能阻止用户从搜索引擎结果中被引导到这个页面。可以利用 Sphinx 的 directives如warning、deprecated、versionchanged或 MkDocs 的 admonitions 来生成这类警告例如.. deprecated:: 1.0 该 API 已弃用请使用 v2 版本。第二步在自定义 robots.txt 中屏蔽该页面要让搜索引擎不再展示该页面可以在项目的自定义robots.txt中为该页面添加Disallow条目# robots.txt User-agent: * Disallow: /en/latest/api/v1.html # Deprecated API关于robots.txt的实现细节readthedocs/proxito/views/serve.py 中的ServeRobotsTXTBase视图说明自定义robots.txt取自项目的default version因为robots.txt需要在域名顶层提供服务必须选择一个版本作为来源若 default version 为私有、未激活或未构建则返回 404若 default version 中没有用户自定义的robots.txt则渲染默认模板。默认模板内容见 readthedocs/templates/robots.txt其中会列出隐藏版本的路径并包含sitemap.xml地址。生成robots.txt的方式因文档工具而异Sphinx 通过html_extra_path配置将静态文件加入最终 HTML 输出MkDocs 则要求robots.txt位于docs_dir目录下详见 docs/user/reference/robots.rst。需要说明的是robots.txt只被大多数搜索引擎尊重而非强制执行搜索引擎可能忽略它并仍然索引你的页面。如果文档必须绝对私有请参考 docs/user/commercial/sharing.rst 的分享/权限方案。第三步通过 search.ranking 降低页内搜索排名即使屏蔽了搜索引擎你的文档站内搜索server-side search仍然会返回该页面的结果。Read the Docs 允许通过配置文件search.ranking为每个页面设置自定义排名。在项目根目录的.readthedocs.yaml中添加# .readthedocs.yaml version: 2 search: ranking: api/v1.html: -1这不会隐藏该页面的结果但会把结果排在其他页面之后从而降低旧内容被点击的概率。search.ranking的完整语法见 docs/user/config-file/v2.rst 的search小节类型map模式到排名的映射默认{}匹配目标构建产出的 HTML 文件的相对路径例如匹配index.html而不是docs/index.rst或/en/latest/index.html特殊字符*匹配任意内容含斜杠、?匹配单个字符、[seq]匹配字符集合取值范围-10到10的整数含端点。越接近-10排名越靠后越接近10排名越靠前0表示正常排名而非无排名规则多个模式匹配同一页面时以最后匹配到的模式为准官方建议降低要弃用页面的排名而不是抬高其他页面的排名。一个更贴近实战的示例同样摘自配置文档version: 2 search: ranking: # 匹配单个文件 tutorial.html: 2 # 匹配 api/v1 目录下的所有文件 api/v1/*: -5 # 同时匹配根目录与嵌套目录下的 guides.html guides.html: 3 */guides.html: 3此外search.ignore可以从搜索索引中完全排除某些路径默认排除search.html、search/index.html、404.html、404/index.html被匹配的页面不会出现在任何搜索结果中——如果你的弃用页面确实希望彻底消失于站内搜索这是比降权更彻底的选项。移除与移动页面用重定向保住旧链接当某功能弃用了一段时间后你可能想彻底删掉它的文档——这完全合理你不需要永远维护那些内容。但请记住用户可能保存了指向该页面的链接直接让他们看到 404 会非常沮丧和困惑。解决方案是为旧页面创建重定向指向具有相似功能或内容的页面。例如把弃用的 API v1 文档重定向到 v2 文档即从/api/v1.html到/api/v2.html的page redirect页面重定向。页面重定向Page Redirect页面重定向作用于所有版本的文档From URL不需要包含/en/latest之类的语言/版本前缀只需要页面路径Type: Page Redirect From URL: /api/v1.html To URL: /api/v2.html访问https://project.readthedocs.io/en/latest/api/v1.html和https://project.readthedocs.io/en/stable/api/v1.html都会被重定向到对应版本的/api/v2.html。精确重定向Exact Redirect如果你只希望重定向某一个具体版本/语言下的页面则使用精确重定向From URL需要包含完整的语言和版本前缀Type: Exact Redirect From URL: /en/latest/api/v1.html To URL: /en/latest/api/v2.html典型的版本弃用场景是把旧版本2.0/en/2.0/的读者引导到新版本3.0/en/3.0/可以使用通配符一次覆盖整个版本Type: Exact Redirect From URL: /en/2.0/* To URL: /en/3.0/:splat*为后缀通配符仅支持后缀通配不支持前缀和中间通配匹配到的部分可通过:splat占位符引用到To URL中。注意要让该重定向生效旧版本必须处于**禁用inactive**状态如果旧版本仍然活跃则需要勾选Force Redirect选项。用户定义重定向的完整限制与示例见 docs/user/user-defined-redirects.rst其中还包括用Force Redirect把/security.html的所有版本强制跳转到latest版本、以及目录级重定向/api/*→/api/v1/:splat等实战用法。弃用策略总结渐进式推进的三个阶段阶段目标手段效果阶段一版本级弃用让整个版本淡出隐藏版本Hidden robots.txt 屏蔽版本菜单不展示、搜索引擎不索引直链仍可访问阶段二页面级弃用让单个页面淡出页内警告 自定义 robots.txt search.ranking降权访问者看到警告、站内站外搜索排名靠后阶段三移除与迁移彻底删除内容但不留 404页面重定向 / 精确重定向必要时 Force旧链接平滑跳转到新页面用户体验无损这套流程的核心原则是弃用是过程不是删除动作。先用隐藏和降权降低旧内容的可见性观察一段时间后再用重定向接管旧链接最后才让内容下线——这样既能逐步引导用户迁移又能保证已有链接不失效是值得在文档维护中长期采用的非破坏性策略。赞分享后端文档【免费下载链接】readthedocs.orgThe source code that powers readthedocs.org项目地址https://gitcode.com/gh_mirrors/re/readthedocs.org点击查看免费下载相关推荐Qbot 回测绘图报 AttributeError: unexpected attribute plot_width to figure 怎么处理Qbot 回测绘图报 AttributeError: unexpected attribute plot_width to figure 怎么处理 在 Q后端文档终极Read the Docs容器化部署指南Docker和Kubernetes完整教程终极Read the Docs容器化部署指南Docker和Kubernetes完整教程 Read the Docs是一个强大的开源文档托管平台能够帮助开发者后端文档Read the Docs 重定向系统设计从五种重定向类型到 * / :splat 新语法与源码实现Read the Docs 重定向系统设计从五种重定向类型到 / :splat 新语法与源码实现 本文基于 Read the Docs下称 RTD的设计文后端文档上一篇10大平台全覆盖SDLPAL跨平台游戏引擎终极指南下一篇Theos安装教程5分钟搞定macOS、Linux和Windows环境配置创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
