Sphinx conf.py添加sys路径后import sys语法错误求助

问题症结 #

你碰到的这个配置错误，核心是个非常容易疏忽的Python语法问题：你把三条语句写在了同一行，却没有正确分隔。你添加的代码：

import sys import os sys.path.insert(0, os.path.abspath('.'))

这完全不符合Python的语法规则——Python要求每条语句单独占一行，或者用分号;分隔同行的多个语句。虽然你觉得和Sphinx示例一致，但示例里肯定是把import sys、import os和路径插入的代码分成三行写的，你大概率是误把它们合并成了一行，导致整个配置文件解析失败。报错信息里指向的第20行import sys其实是原本自动生成的正常代码，只是因为前面的语法错误导致解析器的行号判断出现了偏移。

修复方案 #

1. 修正conf.py的语法
   把你添加的代码拆成标准的多行写法，这是Python的规范：

   import sys
   import os
   sys.path.insert(0, os.path.abspath('.'))
   

   另外，如果你的自定义模块不在conf.py所在的docs目录，而是在项目根目录，得调整路径指向根目录，比如：

   sys.path.insert(0, os.path.abspath('../'))
   

   这样才能让Python找到你项目里的自定义模块。

2. 先单独验证conf.py的语法
   为了避免再踩语法坑，你可以直接用Python解析conf.py来检查：

   python conf.py
   

   如果运行后没有报错，说明语法已经没问题了；要是还有错误，跟着终端提示调整就行。

3. 重新生成文档
   现在回到Sphinx的构建命令，比如：

   sphinx-build -b html docs/source docs/build
   

   这时候autodoc应该就能正常导入你的自定义模块了。

额外小提示 #

• 报错里提到的“Did you change the syntax from 2.x to 3.x?”其实是个误导，你的问题和Python版本切换无关，纯粹是语法错误。
• 要是不确定路径是否正确，可以在conf.py里加个打印语句验证：

  print(sys.path)
  

  执行python conf.py就能看到当前的模块搜索路径，确认你的自定义模块所在目录是否在列表里。

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