使用Sphinx为Python2.7的Cython模块生成文档时遇TypeError

根据你描述的情况，我在维护老项目时遇到过类似的Sphinx+Cython文档生成坑，结合你的怀疑点，给你几个针对性的排查和解决方向：

1. 补全Numpy的Mock范围 #

你提到在conf.py中mock了numpy，但Sphinx 1.7对模块mock的粒度要求很严格，只mock顶层numpy往往不够。尝试扩展mock列表，把numpy的核心类型也包含进去：

import sys
from unittest.mock import Mock

# 覆盖numpy常用类型和子模块，避免解析时找不到类型定义
MOCK_MODULES = [
    'numpy', 
    'numpy.ndarray', 
    'numpy.dtype',
    'numpy.float64',
    'numpy.int32'
]
for mod_name in MOCK_MODULES:
    sys.modules[mod_name] = Mock()

如果用的是autodoc_mock_imports，也要同步添加这些子项：

autodoc_mock_imports = ['numpy', 'numpy.ndarray', 'numpy.dtype']

2. 规范Cython中np.ndarray的声明逻辑 #

哪怕没有.pxd文件，在.pyx里正确导入numpy的Cython接口是关键，否则Sphinx解析签名时会把np.ndarray当成未知类型。确保代码开头有：

# 导入numpy的Cython底层定义
cimport numpy as np
# 同时导入Python层的numpy
import numpy as np

函数声明时尽量明确数组的类型和维度（如果业务允许），比如：

cdef np.ndarray[np.float64_t, ndim=2] process_matrix(np.ndarray[np.float64_t, ndim=2] input_mat):
    # 函数实现
    return input_mat

如果省略cimport numpy直接用np.ndarray，Sphinx大概率会因无法识别类型触发TypeError。

3. 排查空行前后的代码上下文 #

虽然第155行是空的，但Sphinx的签名解析依赖代码上下文，可能前面的函数声明存在语法缺陷，比如遗漏冒号、括号不匹配，或者缩进错误。检查150-160行的代码，确保所有函数定义都正确闭合：

# 错误示例：遗漏函数定义后的冒号
cdef np.ndarray my_func(np.ndarray input)
    # 代码...

# 正确示例
cdef np.ndarray my_func(np.ndarray input):
    # 代码...

4. 调整embedsignature的使用方式 #

Sphinx 1.7对Cython的embedsignature=True支持有限，尤其是Python2.7环境下。可以尝试两种替代方案：

• 暂时禁用embedsignature，依赖Sphinx的autodoc自动提取签名
• 在Cython函数上手动补全文档字符串，明确写出签名，比如：

cdef np.ndarray process_data(np.ndarray input):
    """
    process_data(input)
    
    处理输入数组的核心函数
    
    参数:
        input: numpy数组，待处理的原始数据
    返回:
        numpy数组，处理后的结果数据
    """
    # 函数实现

5. 版本兼容性检查 #

Python2.7、Sphinx1.7、Cython的组合属于老旧技术栈，存在不少已知兼容性bug。尝试升级Cython到支持Python2.7的最新版本（比如0.29.x系列），或者把Sphinx升级到2.4.x（最后一个支持Python2.7的Sphinx版本），可能会解决底层的解析问题。

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