GitLab CI启用autodoc_mock_imports后，如何生成Sphinx子类文档？

你已经找对了方向——用autodoc_mock_imports跳过依赖安装，但问题出在两个关键细节上：.rst里的inherited-members选项会让Sphinx尝试解析mock的父类（而mock对象没有有效结构），导致子类自身的成员也被忽略；另外可能mock的配置需要更精准。

下面是针对你的场景（7个子类、自动化CI构建）的完整步骤：

1. 调整Sphinx配置文件（conf.py） #

首先确保mock覆盖所有必要的依赖，同时关闭不必要的继承相关行为：

# Configuration file for the Sphinx documentation builder.
import os
import sys
# 把你的子类所在目录添加到Python路径，确保Sphinx能找到模块
sys.path.insert(0, os.path.abspath('../'))

# 核心：mock掉TensorFlow及其子模块，无需实际安装
autodoc_mock_imports = ['tensorflow']

# 关闭文档字符串继承，避免Sphinx尝试读取mock父类的无效文档
autodoc_inherit_docstrings = False

# 配置默认的autodoc选项，只关注子类自己的成员
autodoc_default_options = {
    'members': True,          # 显示子类的所有成员函数
    'show-inheritance': False # 不显示继承关系（可选，如果你不需要的话）
}

# 其他基础配置（根据你的项目调整）
project = 'Custom Keras Callbacks'
copyright = '2024, Your Team'
author = 'Your Team'
extensions = ['sphinx.ext.autodoc']
html_theme = 'sphinx_rtd_theme' # 用常用的Read the Docs主题

如果自动mock不生效，可以试试手动mock（更可靠），替换上面的autodoc_mock_imports部分：

import sys
from unittest.mock import Mock

# 手动mock整个TensorFlow依赖链
sys.modules['tensorflow'] = Mock()
sys.modules['tensorflow.keras'] = Mock()
sys.modules['tensorflow.keras.callbacks'] = Mock()
sys.modules['tensorflow.keras.callbacks.Callback'] = Mock()

2. 修正.rst文档指令 #

你原来的.rst里的inherited-members是罪魁祸首——它让Sphinx尝试从mock的父类提取成员，反而导致子类自身的成员被跳过。修改keras_callback.rst：

Custom Keras Callback
=====================

.. automodule:: keras_callback
   :members:
   # 移除:inherited-members:，因为你不需要展示父类成员，且mock对象会干扰解析

如果某些子类成员没有文档字符串但你也想展示，可以加上:undoc-members:选项：

.. automodule:: keras_callback
   :members:
   :undoc-members:

3. GitLab CI自动化构建配置 #

用轻量Python镜像，只安装Sphinx必要依赖，完全不需要TensorFlow。创建/修改.gitlab-ci.yml：

stages:
  - docs

build-and-publish-docs:
  image: python:3.11-slim # 轻量镜像，仅包含基础Python环境
  stage: docs
  before_script:
    # 仅安装Sphinx和主题，无需任何AI/ML依赖
    - pip install --no-cache-dir sphinx sphinx-rtd-theme
  script:
    # 进入Sphinx文档目录（假设你的conf.py在docs/下）
    - cd docs
    # 生成HTML文档到_build/html目录
    - sphinx-build -b html . _build/html
  # 保存生成的文档作为CI产物，方便查看或部署
  artifacts:
    paths:
      - docs/_build/html
    expire_in: 2 weeks # 可选，根据需求调整过期时间
  # 可选：仅在主分支或标签触发构建
  only:
    - main
    - tags

4. 故障排查小技巧 #

• 如果子类模块无法被导入：检查conf.py里的sys.path是否正确指向子类所在的目录（比如如果子类在项目根目录，sys.path.insert(0, os.path.abspath('../'))是对的）
• 如果成员还是不显示：确保子类的成员函数有正确的文档字符串（用三引号包裹的注释），或者添加:undoc-members:选项
• 如果mock还是报错：尝试手动mock的方式，比自动mock更灵活可控

这样配置后，CI构建时完全不需要安装TensorFlow等大依赖，就能自动生成所有子类的文档，完美适配你7个子类的自动化需求。

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