无法通过 GitLab（docker）管道使用 Django 构建 sphinx autodocumentation

Question

这个问题可能很具体。

我的设置

这是我的项目结构。这是一个 Django 项目。

├── 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 实例上，我安装了多个运行器。一个是 docker executor，负责通过 Sphinx 构建文档。

基本的

.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/

只要我没有尝试通过

sphinx-autodoc

扩展包含 Django 代码，它就一直工作得很好。一切都显示在 GitLab 页面上。我知道 Sphinx 需要加载它预先扫描的每个模块。所以这就是为什么你必须在

conf.py

.

中初始化 Django

我的狮身人面像

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()

调用

django.setup()

之前的最后一行确保包含项目级路径。 当我

make html

在我的本地系统上时，Autodocumenting Django 可以很好地处理这些修改。我指定的模块被很好地记录下来，没有发生错误。

现在我的实际问题

我将代码推送到我的 GitLab 存储库，并让作业通过 docker 执行程序运行。

$ python3 -m pip install django sphinx furo myst-parser
Collecting django
  Downloading Django-4.1.7-py3-none-any.whl (8.1 MB)
     ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 8.1/8.1 MB 124.3 MB/s eta 0:00:00
Collecting sphinx
  Downloading sphinx-6.1.3-py3-none-any.whl (3.0 MB)
     ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 3.0/3.0 MB 111.0 MB/s eta 0:00:00
...
# the loading continues here

加载所有模块后，它会尝试执行 Sphinx。现在，出现此错误：

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

据我所知，这通常发生在您没有正确设置路径变量时。但是我在项目级别设置它并将其打印出来作为验证（错误消息中的

### lines

）。我的项目路径肯定是

/builds/my-dir/my-project-name

.

你对我可以尝试让它发挥作用有什么想法吗？

Answer 1

好吧-我是个大白痴。

sys.path.append(Path(__file__).parent.parent.parent.as_posix())

挽救了一天。