GitLab Docker流水线中Sphinx生成Django自动文档失败求助

问题 #

在私有GitLab实例上托管了一个Django项目，使用Docker执行器的GitLab流水线通过Sphinx构建文档。未启用sphinx-autodoc扩展时流水线运行正常，但启用该扩展后，流水线执行sphinx-build时出现ModuleNotFoundError，提示找不到'my-project-name'模块。

本地执行make html可正常生成包含Django代码的自动文档，Sphinx的conf.py中已添加项目路径并初始化Django，且已确认流水线中的项目路径为/builds/my-dir/my-project-name。

项目结构 #

├── docs
│   ├── build
│   │   ├── doctrees
│   │   └── html
│   ├── Makefile
│   └── source
│       ├── code
│       ├── conf.py
│       ├── contributing.md
│       ├── index.rst
│       ├── infrastructure.md
│       └── _static
├── my-project-name
│   ├── api.py
│   ├── asgi.py
│   ├── celeryconfig.py
│   ├── celery.py
│   ├── __init__.py
│   ├── __pycache__
│   ├── routers.py
│   ├── settings.py
│   ├── urls.py
│   └── wsgi.py
|   ... some more apps

.gitlab-ci.yml配置 #

image: python:3.10-slim

stages:
- deploy

pages:
  tags:
  - docs
  stage: deploy
  script:
  - python3 -m pip install django sphinx furo myst-parser
  - sphinx-build -b html docs/source public/

conf.py初始化部分 #

# Sphinx needs Django loaded to correctly use the "autodoc" extension
import django
import os
import sys
from pathlib import Path

os.environ.setdefault("DJANGO_SETTINGS_MODULE", "my-project-name.settings")
sys.path.append(Path(__file__).parent.parent.parent)

django.setup()

流水线报错信息 #

WARNING: Running pip as the 'root' user can result in broken permissions and conflicting behaviour with the system package manager. It is recommended to use a virtual environment instead: https://pip.pypa.io/warnings/venv
[notice] A new release of pip available: 22.3.1 -> 23.0.1
[notice] To update, run: pip install --upgrade pip
$ sphinx-build -b html docs/source public/
Running Sphinx v6.1.3
######
/builds/my-dir/my-project-name
######
Configuration error:
There is a programmable error in your configuration file:
Traceback (most recent call last):
  File "/usr/local/lib/python3.10/site-packages/sphinx/config.py", line 351, in eval_config_file
    exec(code, namespace)  # NoQA: S102
  File "/builds/my-dir/my-project-name/docs/source/conf.py", line 22, in <module>
    django.setup()
  File "/usr/local/lib/python3.10/site-packages/django/__init__.py", line 19, in setup
    configure_logging(settings.LOGGING_CONFIG, settings.LOGGING)
  File "/usr/local/lib/python3.10/site-packages/django/conf/__init__.py", line 92, in __getattr__
    self._setup(name)
  File "/usr/local/lib/python3.10/site-packages/django/conf/__init__.py", line 79, in _setup
    self._wrapped = Settings(settings_module)
  File "/usr/local/lib/python3.10/site-packages/django/conf/__init__.py", line 190, in __init__
    mod = importlib.import_module(self.SETTINGS_MODULE)
  File "/usr/local/lib/python3.10/importlib/__init__.py", line 126, in import_module
    return _bootstrap._gcd_import(name[level:], package, level)
  File "<frozen importlib._bootstrap>", line 1050, in _gcd_import
  File "<frozen importlib._bootstrap>", line 1027, in _find_and_load
  File "<frozen importlib._bootstrap>", line 992, in _find_and_load_unlocked
  File "<frozen importlib._bootstrap>", line 241, in _call_with_frames_removed
  File "<frozen importlib._bootstrap>", line 1050, in _gcd_import
  File "<frozen importlib._bootstrap>", line 1027, in _find_and_load
  File "<frozen importlib._bootstrap>", line 1004, in _find_and_load_unlocked
ModuleNotFoundError: No module named 'my-project-name'
Cleaning up project directory and file based variables
00:01
ERROR: Job failed: exit code 1

解决办法 #

1. 修正sys.path的添加优先级和路径格式 #

把项目根目录转为绝对路径并插入到sys.path的最前面，确保Python优先从该目录查找模块：

# 替换conf.py中原sys.path.append的代码
project_root = Path(__file__).parent.parent.parent.resolve()
sys.path.insert(0, str(project_root))

resolve()确保路径为绝对路径，insert(0)提升该目录的模块查找优先级。

2. 在流水线中以可编辑模式安装项目 #

修改GitLab流水线脚本，添加项目的可编辑安装步骤，让Python全局识别项目模块：

# 更新.gitlab-ci.yml的script部分
script:
- python3 -m pip install --upgrade pip
- python3 -m pip install django sphinx furo myst-parser
- pip install -e .  # 以可编辑模式安装当前项目
- sphinx-build -b html docs/source public/

pip install -e .会将项目根目录添加到Python的site-packages中，确保模块能被正确导入。

3. 验证并切换到正确的工作目录 #

在流水线脚本中添加目录验证命令，确认当前工作目录是否为项目根目录，若不是则切换：

script:
- pwd  # 输出当前工作目录，确认是否为/builds/my-dir/my-project-name
- cd /builds/my-dir/my-project-name || exit 1
- python3 -m pip install django sphinx furo myst-parser
- sphinx-build -b html docs/source public/

4. 调试路径正确性 #

在conf.py中添加调试输出，确认项目根目录和模块目录是否存在：

project_root = Path(__file__).parent.parent.parent.resolve()
print(f"Project root: {project_root}")
print(f"Module directory exists: {(project_root / 'my-project-name').exists()}")
sys.path.insert(0, str(project_root))

通过流水线日志查看输出，确认路径是否正确。

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