如何在Read the Docs上正确配置PyQt5导入以构建Sphinx文档？

我之前给PyQt5项目做Sphinx文档构建时，也踩过一模一样的坑！这俩错误本质都是Qt在无图形界面环境下的“水土不服”：

• QStandardPaths: XDG_RUNTIME_DIR not set：Qt找不到标准的运行时目录，需要把这个环境变量传递给构建进程
• Could not connect to any X display：Qt依赖X显示服务器，但构建文档的环境（比如CI服务器、无桌面的Linux主机）没有真实显示器，得用虚拟显示来模拟

直接在你的tox.ini里添加docs测试环境的配置就能搞定：

[testenv:docs]
# 传递XDG_RUNTIME_DIR环境变量，解决第一个报错
passenv = XDG_RUNTIME_DIR
# 用xvfb-run启动sphinx-build，虚拟一个X显示服务器，解决第二个报错
commands = /usr/bin/xvfb-run sphinx-build --color -W -b html docs/source docs/build/html

额外说明： #

• 先确保你的系统装了xvfb包：Debian/Ubuntu系用sudo apt install xvfb，RHEL/CentOS系用sudo dnf install xorg-x11-server-Xvfb
• 调整sphinx-build后面的路径参数，把docs/source换成你实际的文档源目录，docs/build/html换成你想要的HTML输出目录
• -W参数是让Sphinx把所有警告当成错误，强制修复文档里的问题，要是觉得太严格可以删掉这个参数

内容的提问来源于stack exchange，提问作者ederag