后端文档【免费下载链接】readthedocs.orgThe source code that powers readthedocs.org项目地址https://gitcode.com/gh_mirrors/re/readthedocs.org点击查看免费下载本文是 readthedocs.org 开源仓库中 docs/user/faq.rst 用户常见问题文档的深度展开版。它围绕“构建与发布、附加功能与配置、大型项目、Sphinx、Python 依赖、其他文档框架”六类高频问题逐一给出可直接落地的操作步骤与配置示例并结合仓库源码如 配置解析器、构建环境变量说明其底层机制。读完本文你将掌握 Read the Docs 构建失败的排查路径、.readthedocs.yaml依赖安装的完整写法、READTHEDOCS环境变量的用法以及多语言、多项目共域名的部署方案。构建与发布从失败到成功为什么我的项目状态是 failing项目状态显示为failing说明构建过程中某个环节失败了。常见原因有三类项目配置不正确例如.readthedocs.yaml中指定了错误的构建工具或路径Git 仓库内容本身无法构建如源码存在语法错误、缺少依赖极少数情况下Read the Docs 所连接的外部系统不可用。排查的第一步永远是打开项目的Builds构建标签页点击失败的步骤step查看详细的错误日志。日志中的关键报错信息可以直接用于搜索解决方案。如果错误信息不能一眼看出原因请从报错中提取一个重要单词或一段关键消息进行检索。可参考的深度资料构建失败的常见错误与解决方案参见 docs/user/guides/troubleshooting/ 目录下的构建故障排查指南系统级依赖缺失的问题见下文“C 模块导入错误”一节添加额外软件依赖的通用方法见“如何为文档添加额外的软件依赖”一节。为什么我会遇到依赖 C 模块的库的导入错误这类报错通常发生在构建环境中缺少编译 Python 包所需的系统级 C 库例如libevent、mysql等。另一种常见触发场景是模块本身带有 C 扩展导致autodoc在导入模块时执行了编译期代码而失败。解决方案分两步第一步通过build.apt_packages安装系统库。在.readthedocs.yaml中声明构建所需 Debian/Ubuntu 软件包version: 2 build: apt_packages: - libclang - cmake该配置项的完整定义见 docs/user/config-file/v2.rst#L505-L533类型为list默认值为[]。Read the Docs 的构建服务器运行各版本的 Ubuntu LTS并使用默认软件源目前不支持 PPA 或其他自定义软件源。同时注意当使用build.commands自定义构建时build.apt_packages不可用。从源码看该配置在 配置解析器 validate_apt_packages 方法 中被逐项校验raw_packages读取自build.apt_packages键随后对每个包调用validate_apt_package检查其合法性非法值会抛出带build.apt_packages.index定位信息的校验错误。对应的单元测试覆盖了合法值、非法类型与非法值三种情况见 readthedocs/config/tests/test_config.py#L805-L836。第二步对无法通过 apt 安装的库使用autodoc_mock_imports模拟导入。在 Sphinx 的conf.py中import sys from unittest.mock import MagicMock # 示例把缺失 C 依赖的模块替换为 mock sys.modules[mysql] MagicMock()Sphinx 官方内置了autodoc_mock_imports配置用于在autodoc阶段模拟导入这些模块。若这些库是通过setup.py安装的还需在 Read the Docs 构建环境中把 C 依赖库从install_requires中移除避免构建环境尝试真实安装它们。我的文档应该放在仓库的哪个位置Read the Docs 对文档在仓库中的存放位置没有强制要求——你可以放在任意目录。关键在于必须通过 Read the Docs 配置文件.readthedocs.yaml告诉平台Sphinx 的conf.py或 MkDocs 的mkdocs.yml在哪里version: 2 sphinx: configuration: docs/conf.pyversion: 2 mkdocs: configuration: mkdocs.yml对应的配置键是sphinx.configuration与mkdocs.configuration。配置文件本身的全量参考见 docs/user/config-file/index.rst 与 docs/user/config-file/v2.rst。如何避免搜索结果返回我文档的过期版本当读者在 Google 中搜索你的文档时搜索引擎可能返回“相关性最高”的版本而这个版本恰好已经废弃。你希望停止 Google 索引旧版本、改推最新版。做法是在文档根目录放置robots.txt让它被服务在项目根 URL 下例如https://yourproject.readthedocs.io/robots.txt。具体配置方式已完整记录在 docs/user/reference/robots.rst包括如何基于版本元数据如READTHEDOCS_VERSION动态生成规则以及如何声明新版本为 canonical 页面。如何修改项目的版本 slug版本Version的 URL 标识符slug可以在项目的Versions版本标签页中修改。slug 决定了该版本文档的访问路径例如latest、v1.2等。详细操作见 docs/user/versions.rst 中“Version URL identifier (slug)”一节。线上部署的 Read the Docs 是哪个 commitreadthedocs.org 生产环境从仓库的rel分支部署。想查看最新已部署的提交可查阅rel分支的提交历史同时仓库维护了一份持续更新的 CHANGELOG.rst对应的用户文档是 docs/user/changelog.rst可用于追踪功能演进与版本行为变化。附加功能与配置如何为文档添加额外的软件依赖对大多数 Python 依赖推荐用requirements 文件声明version: 2 python: install: - requirements: docs/requirements.txt - requirements: requirements.txtpython.install的类型为list默认值为[]支持同时列出多个条目requirements键的值为相对项目根目录的路径见 docs/user/config-file/v2.rst#L140-L179。除 requirements 文件外你也可以让构建环境直接以 pip 方式安装你的 Python 项目本身见下文“非仓库根目录的 Python 包”一节。相关的深度资料构建过程整体概览docs/user/builds.rst依赖管理与维护最佳实践docs/user/guides/reproducible-builds.rst自定义构建如使用 Sphinx 之外的工具、为基于 Ubuntu 的构建器添加软件包docs/user/config-file/v2.rst 中的build一节主配置文件.readthedocs.yaml的完整参考docs/user/config-file/v2.rst。如何在 Read the Docs 构建时改变行为Read the Docs 在构建项目时会设置环境变量READTHEDOCS其值为字符串True。因此你可以在 Sphinx 的conf.py中根据它动态切换行为import os on_rtd os.environ.get(READTHEDOCS) True if on_rtd: html_theme default else: html_theme nature该变量同样存在于 Sphinx 的构建模板环境中可用于 Jinja 模板{% if READTHEDOCS %} Woo {% endif %}从源码看构建总监 Director 的 get_rtd_env_vars 方法 为每个构建统一注入了READTHEDOCS及其一整套运行时变量包括READTHEDOCS_VERSION当前构建的版本 slugREADTHEDOCS_VERSION_TYPE版本类型如branch、tag、externalREADTHEDOCS_VERSION_NAME版本的显示名称READTHEDOCS_PROJECT项目 slugREADTHEDOCS_LANGUAGE项目语言READTHEDOCS_REPOSITORY_PATH源码检出路径READTHEDOCS_OUTPUT构建产物输出目录检出路径/_readthedocs/READTHEDOCS_GIT_COMMIT_HASH等 Git 相关信息。此外构建环境中还提供READTHEDOCS_VIRTUALENV_PATH虚拟环境路径与UV_PROJECT_ENVIRONMENT指向同一 venv参见 readthedocs/doc_builder/python_environments.py#L132-L151。这意味着你不仅能在conf.py中感知“是否在 RTD 构建”还能拿到版本、项目、输出目录等完整上下文实现按版本定制主题、按语言切换内容等高级逻辑。我想在文档中加入评论功能Read the Docs本身不提供评论功能。但可以通过第三方工具实现例如 Disqus 以及对应的 Sphinx 插件sphinxcontrib-disqus在文档页面中嵌入 Disqus 代码块即可为每个页面挂载评论区。实现方式与一般 Sphinx 项目一致评论区的配置和数据托管在第三方服务上。我可以移除文档中的广告吗可以。Read the Docs 提供广告退出Opting Out机制具体操作参见 docs/user/advertising/ethical-advertising.rst 中“Opting Out”一节该功能与订阅方案相关。如何修改项目 slug文档服务的 URLRead the Docs 不支持直接修改项目 slug。你只能更新站点上显示的项目名称而不能更改文档实际服务的 URL。原因在于修改 slug 会使所有指向旧 URL 的内容链接失效。可选的替代方案删除并重建同名项目来获得新 slug——但如果你已有入站链接强烈不建议这么做因为它会“破坏互联网”改变 URL 即破坏既有引用迁移文档到另一个域名通过用户自定义重定向实现见 docs/user/user-defined-redirects.rst若上述方案都不满足可发邮件至 supportreadthedocs.org 请求人工处理。大型项目多项目与多语言如何在同一个自定义域名下托管多个项目Read the Docs 支持subprojects子项目概念多个项目可以共享一个域名。把子项目添加到某个项目后该子项目文档就会被服务在父项目的子域名或自定义域名下。例如Kombu 是 Celery 的子项目因此可以通过 Celery 的域名访问https://celery.readthedocs.io/projects/kombu/en/latest/自定义域名同样适用http://docs.celeryq.dev/projects/kombu/en/latest/在项目管理后台admin dashboard即可添加子项目。自定义域名的详细配置见 docs/user/custom-domains.rst子项目功能本身的文档见 docs/user/subprojects.rst。如何支持文档的多语言版本Read the Docs 原生支持多语言。需要为每个语言创建独立的翻译版本并启用翻译translations功能具体步骤见 docs/user/localization.rst。该文档覆盖了从添加语言、上传翻译文件到配置语言切换的完整流程。Sphinx 专题我想使用 Read the Docs 主题在 Sphinx 项目的conf.py中指定主题即可。Read the Docs 官方主题是sphinx-rtd-theme安装与启用方法遵循 sphinx-rtd-theme 官方文档的标准流程# conf.py html_theme sphinx_rtd_theme并确保在requirements.txt中加入sphinx-rtd-theme依赖管理方式见 docs/user/guides/reproducible-builds.rst。图片缩放在我的文档中不起作用docutils的图片缩放功能依赖Pillow库。如果 Sphinx 项目中的图片缩放异常请在 requirements 中加入Pillow修复# requirements.txt Pillow依赖定义的最佳实践同样参见 docs/user/guides/reproducible-builds.rst。Python 包与依赖安装我可以文档化一个不在仓库根目录的 Python 包吗可以。最方便的方式是用python.install的method: pip配置让 Read the Docs 把包安装进构建文档所用的虚拟环境中这样文档工具如 Sphinx 的 autoapi 扩展就能访问到它version: 2 python: install: - path: path/to/package method: pip其中path是相对项目根目录的包路径method支持pip默认、setuptools已弃用与uv还可用extra_requirements安装额外依赖例如pip install .[docs]完整定义见 docs/user/config-file/v2.rst#L181-L214。从配置源码看validate_python_installreadthedocs/config/config.py#L545-L602会校验requirements、path、method与extra_requirements的组合关系例如extra_requirements仅与method: pip兼容而对应测试则覆盖了默认值、非法 method、路径缺失等十余种场景readthedocs/config/tests/test_config.py#L901-L1248。Read the Docs 与“易读”风格的 docstring 配合得好吗好。Sphinx 的传统注释式 docstring 往往信息密集、不易阅读因此许多项目采用更易读的自定义 docstring 风格其中NumPy 风格与Google 风格最为流行。Read the Docs 默认主题对这两种格式都支持良好前提是conf.py配置了能解析这些 docstring 的 Sphinx 扩展numpydoc处理 NumPy 风格napoleon即 sphinxcontrib-napoleon唯一能同时处理两种风格的扩展且其默认输出更接近标准 Sphinx 注释格式与默认主题搭配观感更佳。# conf.py extensions [ sphinx.ext.autodoc, sphinx.ext.napoleon, ]使用这些扩展时需在项目依赖中显式声明sphinxcontrib-napoleon方式见 docs/user/guides/reproducible-builds.rst。我需要在固定版本的环境里安装一个包如果你希望把依赖固定在包之外可以在 requirements 文件或 Conda 环境文件中加入可编辑安装editable install指令使当前项目以开发模式安装并锁定其依赖版本。在requirements.txt中# path to the directory containing setup.py relative to the project root -e .在 Conda 环境文件environment.yml中# path to the directory containing setup.py relative to the environment file -e ..注意两条路径的相对基准不同requirements.txt中的-e .相对项目根目录而environment.yml中的-e ..相对环境文件所在目录。这样既固定了包的依赖版本又让文档构建环境能直接导入该包。其他文档框架Jupyter Book 部署如何在 Read the Docs 上部署 Jupyter Book 项目Jupyter Book 是一个基于计算材料构建高质量书籍与文档的开源项目。虽然Jupyter Book 几乎完全依赖 Sphinx但它刻意对用户隐藏 Sphinx 的conf.py改为在构建时从其声明式配置_config.yml动态生成。因此要让 Jupyter Book 在 Read the Docs 上工作需要一些额外步骤。核心思路在构建前把 Jupyter Book 项目手动转换为 Sphinx 项目。在.readthedocs.yaml中使用build.jobs.pre_build钩子执行转换命令# .readthedocs.yaml build: jobs: pre_build: # Generate the Sphinx configuration for this Jupyter Book so it builds. - jupyter-book config sphinx docs/build.jobs允许在 Read the Docs 预定义构建步骤的前后注入自定义命令见 docs/user/config-file/v2.rst#L536-L580pre_build即在正式构建之前运行。jupyter-book config sphinx docs/会读取docs/下的 Jupyter Book 配置并生成等价的 Sphinx 配置之后 Read the Docs 便以标准的 Sphinx 流程完成构建。注意使用build.jobs时还需同时指定build.os与build.tools。附核心参考索引主题仓库内位置FAQ 原文docs/user/faq.rst配置文件完整参考docs/user/config-file/v2.rst构建流程概览docs/user/builds.rst可复现构建与依赖管理docs/user/guides/reproducible-builds.rst构建环境变量注入实现readthedocs/doc_builder/director.py#L766-L787配置校验实现readthedocs/config/config.py#L438-L450配置校验测试readthedocs/config/tests/test_config.py以上六类 FAQ 覆盖了从“构建失败如何排查”到“多语言、多项目如何组织”的完整链路先用 Builds 标签页定位失败步骤再通过.readthedocs.yaml的build.apt_packages与python.install解决系统级与 Python 级依赖利用READTHEDOCS环境变量实现环境感知的定制逻辑最后借助子项目、自定义域名、robots.txt 与构建钩子完成生产级文档站点的部署与维护。赞分享后端文档【免费下载链接】readthedocs.orgThe source code that powers readthedocs.org项目地址https://gitcode.com/gh_mirrors/re/readthedocs.org点击查看免费下载相关推荐在 Read the Docs 上部署 Docusaurus 站点配置、构建与集成指南在 Read the Docs 上部署 Docusaurus 站点配置、构建与集成指南 导读 本文基于 Read the Docs 官方文档 docs/use后端文档在 Read the Docs 上部署 MyST Markdown 文档零配置迁移与完整构建实战在 Read the Docs 上部署 MyST Markdown 文档零配置迁移与完整构建实战 MyST MarkdownMyST是一套开源、社区驱动的后端文档10 分钟跑通你的第一个 TransformersTransformers-Tutorials 上百个 HuggingFace Notebook 实战指南10 分钟跑通你的第一个 TransformersTransformers Tutorials 上百个 HuggingFace Notebook 实战指南 听后端文档上一篇无界 Wujie 微前端实战三步接入、三种模式与高频坑的完整指南下一篇快速搭建个人WebDAV服务器从启动到长期运行的完整教程创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考