Sphinx构建regression_testing_package文档时找不到regression_testing.common模块

核心排查方向与解决方案 #

• 检查虚拟环境一致性
  即使全局安装了regression-testing-common，Sphinx可能运行在regression_testing_package的Poetry虚拟环境中。激活对应虚拟环境：poetry shell，然后用poetry show regression-testing-common确认依赖已安装；若未安装，执行poetry add ../regression_testing_common将本地模块作为开发依赖引入。

• 调整sys.path添加顺序
  在conf.py中优先添加regression_testing_common的src路径，避免命名空间解析冲突：

  import sys
  from pathlib import Path
  
  # 先添加common模块的src路径
  common_src = Path(__file__).parent.parent / "regression_testing_common" / "src"
  sys.path.insert(0, str(common_src.resolve()))
  # 再添加当前package的src路径
  package_src = Path(__file__).parent.parent / "regression_testing_package" / "src"
  sys.path.insert(0, str(package_src.resolve()))
  

• 确保命名空间包合规
  两个模块需遵循PEP 420命名空间规范：移除regression_testing目录下的__init__.py文件（若存在），保证命名空间能被Python正确合并。

• 强制触发命名空间注册
  在conf.py中显式导入regression_testing.common，帮助Sphinx识别命名空间：

  try:
      import regression_testing.common
  except ImportError as e:
      print(f"Import error: {e}")
  

验证流程 #

1. 在虚拟环境中手动测试导入：python -c "from regression_testing.azure.pipelines import *"，确认无报错
2. 重新构建文档：sphinx-build -b html docs/source docs/build

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