如何让Sphinx识别虚拟环境中的xmltodict模块？

以下是几个排查和解决的步骤：

• 确认Sphinx运行在虚拟环境中
  执行which sphinx-build（Linux/macOS）或where sphinx-build（Windows），查看输出路径是否指向你的虚拟环境目录（比如.venv/bin/sphinx-build或.venv/Scripts/sphinx-build）。如果路径是全局的，说明你没正确激活虚拟环境，重新激活后再运行构建命令。

• 修正Sphinx配置文件的Python路径
  打开Sphinx的conf.py，在文件开头添加项目根目录到Python路径，确保autodoc能找到你的模块和依赖：

  import sys
  from pathlib import Path
  # 根据你的项目结构调整路径，比如如果conf.py在source目录，项目根在上级目录
  sys.path.insert(0, str(Path(__file__).parent.parent))
  

  同时检查conf.py里的autodoc_mock_imports，如果里面包含xmltodict，立刻移除——mock会让autodoc跳过实际导入，导致依赖找不到的错误。

• 验证虚拟环境中的依赖
  激活虚拟环境后，打开Python交互环境，执行import xmltodict，如果报错说明依赖没装对。这时重新执行poetry install，确保所有依赖都正确安装到虚拟环境中。

• 检查pyproject.toml的依赖配置
  确认xmltodict是在[tool.poetry.dependencies]节点下（如果是运行时依赖），或者[tool.poetry.dev-dependencies]（如果仅开发时用）。如果放在错误的节点下，poetry可能不会在当前环境安装它。

• 清理Sphinx缓存后重新构建
  删除整个build目录，然后重新执行构建命令：

  sphinx-build -b html source build
  

  （注：你原来的命令用了-b source，这可能是笔误，通常构建HTML文档用-b html）

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