mkdocstrings无法识别src目录下模块的问题求助

问题根源 #

Python解释器默认不会将项目根目录下的src/路径加入模块搜索列表（sys.path），因此mkdocstrings无法定位到该目录下的module模块。而把模块移到仓库根目录时，根目录默认在sys.path中，所以插件能正常识别。

可行解决方案 #

方法1：通过mkdocs.yml配置路径 #

直接在mkdocs.yml中给mkdocstrings的Python处理器指定模块所在路径：

plugins:
  - mkdocstrings:
      handlers:
        python:
          path:
            - src  # 添加src目录到模块搜索路径

配置完成后重新执行mkdocs build，插件就能识别src/module下的代码了。

方法2：通过启动脚本手动添加路径 #

如果上述配置不生效，可在项目根目录创建启动脚本mkdocs_run.py，手动把src加入sys.path后再启动mkdocs：

import sys
from pathlib import Path
from mkdocs.__main__ import cli

# 将src目录加入模块搜索路径
sys.path.insert(0, str(Path(__file__).parent / "src"))

# 执行build命令（如需其他命令，替换"build"即可）
sys.argv.insert(1, "build")
cli()

之后运行python mkdocs_run.py替代原有的mkdocs build命令即可。

验证方式 #

修改配置或使用启动脚本后，重新执行构建命令，若不再出现No module named 'module'的错误，说明配置生效。

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