GitLab Pages部署Sphinx文档时无法找到部分模块求助

问题概述 #

在GitLab Pages部署Sphinx文档时，部分模块无法被识别，本地执行相同操作可正常生成完整文档，但GitLab端始终找不到这些模块，生成的文档目录缺失相关内容。

相关配置与日志 #

gitlab-ci.yaml配置 #

# The Docker image that will be used to build your app
image: python:3.12.4-slim

pages:
  script:
    - apt-get update && apt-get install ffmpeg libsm6 libxext6  -y
    - sudo apt-get install python3-sphinx -y
    - pip install -U rst-to-myst[sphinx]
    - pip install -r requirements.txt
    - pip install myst-parser
    - pip install sphinxawesome-theme
    - pip install autodocsumm
    - sphinx-build -b html ./docs/source public
  tags:
    - linux
  artifacts:
    paths:
      # The folder that contains the files to be exposed at the Page URL
      - public
  #rules:
    # This ensures that only pushes to the default branch will trigger
    # a pages deploy
    #- if: $CI_COMMIT_REF_NAME == $CI_DEFAULT_BRANCH

docs/source/conf.py配置 #

import os
import sys


sys.path.insert(0, os.path.join(os.path.dirname(os.path.realpath(__file__)), os.path.abspath('../../va_sdk')))
sys.path.insert(1, os.path.join(os.path.dirname(os.path.realpath(__file__)), os.path.abspath('../../.')))

import va_sdk

# -- Project information -----------------------------------------------------

project = va_sdk.__name__
release = va_sdk.__version__

# -- General configuration ---------------------------------------------------

extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.autosummary',
    'sphinx.ext.napoleon',
    'sphinx.ext.viewcode',
    'sphinx.ext.coverage',
    'myst_parser',
    'autodocsumm',
]
source_suffix = {
    '.rst': 'restructuredtext',
    '.md': 'markdown',
}
napoleon_google_docstring = True
napoleon_numpy_docstring = True
autosummary_generate = True

templates_path = ['_templates']
exclude_patterns = []

# -- Options for HTML output -------------------------------------------------

html_theme = 'sphinxawesome_theme'
html_static_path = ['_static']

GitLab Pages部署日志 #

[path]/edge_sdk/docs/source/md_pages/Документация пакета va_sdk.rst:23: WARNING: autosummary: failed to import va_sdk.components.
Possible hints:
* ModuleNotFoundError: No module named 'va_sdk.va_sdk'
* AttributeError: module 'VA SDK' has no attribute 'components'
* AttributeError: module 'VA SDK' has no attribute 'va_sdk'
* ImportError: 
* ImportError: libGL.so.1: cannot open shared object file: No such file or directory
[path]/edge_sdk/docs/source/md_pages/Документация пакета va_sdk.rst:23: WARNING: autosummary: failed to import va_sdk.run.
Possible hints:
* ModuleNotFoundError: No module named 'va_sdk.va_sdk'
* AttributeError: module 'VA SDK' has no attribute 'run'
* AttributeError: module 'VA SDK' has no attribute 'va_sdk'
* ImportError: 
* ImportError: libGL.so.1: cannot open shared object file: No such file or directory
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
copying assets... copying static files... done
copying extra files... done
done

项目目录结构 #

/
└───edge_sdk
    ├───config
    ├───docs
    │   ├───images
    │   └───topics
    ├───example
    ├───logs
    ├───va_sdk  # 包含__init__.py的子模块
    │   ├───components # 包含__init__.py的子模块
    │   │   ├───monitoring # 包含__init__.py的子模块
    │   │   └───utils_process # 包含__init__.py的子模块
    │   ├───schema # 包含__init__.py的子模块
    │   └───utils # 包含__init__.py的子模块
    └───tests
        ├───mockup
        ├───test_core
        ├───test_process
        └───test_utils

解决方案 #

1. 修复sys.path路径配置 #

原conf.py中先将va_sdk目录加入sys.path，导致Python把该目录当成顶层包，尝试导入va_sdk.components时会错误地在va_sdk目录下寻找va_sdk子包。修改conf.py的sys.path配置：

import os
import sys

# 获取项目根目录（edge_sdk文件夹路径）
current_dir = os.path.dirname(os.path.realpath(__file__))
project_root = os.path.abspath(os.path.join(current_dir, '../../'))
# 将项目根目录加入sys.path最前端
sys.path.insert(0, project_root)

import va_sdk

2. 补充缺失的系统依赖 #

日志中提示libGL.so.1缺失，这是因为slim版Python镜像缺少OpenGL相关库。在gitlab-ci.yaml的apt安装命令中添加对应依赖：

- apt-get update && apt-get install ffmpeg libsm6 libxext6 libgl1-mesa-glx -y

3. 确保本地包正确安装 #

在gitlab-ci.yaml的script中添加本地包安装命令，确保GitLab环境能正确识别va_sdk模块：

- pip install -e ./edge_sdk

4. 验证环境一致性 #

检查requirements.txt是否包含所有依赖项，确保GitLab环境与本地依赖版本一致，避免因版本差异导致的导入问题。

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