如何解决Sphinx-doc中Protobuf类型文档显示混乱的问题？

我之前解决过这个问题，但现在又失效了。基于Protobuf和gRPC开发时，生成的文档里所有枚举类型显示得极为混乱：

create_session(name: str, path: str, file_type: <google.protobuf.internal.enum_type_wrapper.EnumTypeWrapper object at 0x10984e7d0> = 0, sample_rate: <google.protobuf.internal.enum_type_wrapper.EnumTypeWrapper object at 0x109837710> = 2, bit_depth: <google.protobuf.internal.enum_type_wrapper.EnumTypeWrapper object at 0x10982c6d0> = 2, io_setting: <google.protobuf.internal.enum_type_wrapper.EnumTypeWrapper object at 0x109819d10> = 1, is_interleaved: bool = True)

对应的源码函数如下：

import ptsl.PTSL_pb2 as pt # my grpc-tools generated type header

# ...

def create_session(self,
                   name: str,
                   path: str,
                   file_type: 'SessionAudioFormat' = pt.SAF_WAVE,
                   sample_rate: 'SampleRate' = pt.SR_48000,
                   bit_depth: 'BitDepth' = pt.Bit24,
                   io_setting: 'IOSettings' = pt.IO_Last,
                   is_interleaved: bool = True) -> None:

# ...

源码里的类型注解被转成了类型实例，没法显示真实类型名称，也不能链接到我已经写好的对应类型文档。有没有办法让文档解析出真实类型名称，并且像其他类型一样链接到对应文档？

1. 直接引用生成的枚举类 #

gRPC生成的Protobuf枚举都有对应的类（比如pt.SessionAudioFormat），把字符串类型注解换成直接引用枚举类就行：

def create_session(self,
                   name: str,
                   path: str,
                   file_type: pt.SessionAudioFormat = pt.SAF_WAVE,
                   sample_rate: pt.SampleRate = pt.SR_48000,
                   bit_depth: pt.BitDepth = pt.Bit24,
                   io_setting: pt.IOSettings = pt.IO_Last,
                   is_interleaved: bool = True) -> None:

这样文档生成工具能直接识别枚举类型，不会把默认值的实例当成类型来显示。

2. 用typing.Type明确标注（保留延迟导入） #

如果需要保留字符串注解的延迟导入特性，就用typing.Type包裹枚举类：

from typing import Type

def create_session(self,
                   name: str,
                   path: str,
                   file_type: Type['pt.SessionAudioFormat'] = pt.SAF_WAVE,
                   sample_rate: Type['pt.SampleRate'] = pt.SR_48000,
                   bit_depth: Type['pt.BitDepth'] = pt.Bit24,
                   io_setting: Type['pt.IOSettings'] = pt.IO_Last,
                   is_interleaved: bool = True) -> None:

这能告诉文档工具，这里的类型是枚举本身，不是枚举的实例。

3. 配置文档生成工具（以Sphinx为例） #

要是用Sphinx生成文档，得确保sphinx.ext.autodoc和sphinx.ext.intersphinx启用，然后在conf.py里加这些配置：

autodoc_type_aliases = {
    'SessionAudioFormat': 'ptsl.PTSL_pb2.SessionAudioFormat',
    'SampleRate': 'ptsl.PTSL_pb2.SampleRate',
    # 其他枚举类型照猫画虎加进去
}

# 让类型提示显示更简洁，方便生成链接
autodoc_typehints_format = 'short'

这样Sphinx会把类型别名映射到真实的枚举类，生成可点击的文档链接。

4. 修复Protobuf生成代码的类型提示（可选） #

如果gRPC生成的代码类型提示不对，可以用protoc-gen-mypy插件生成带正确类型注解的存根文件：

python -m grpc_tools.protoc \
    --python_out=. \
    --grpc_python_out=. \
    --mypy_out=. \
    your_proto_file.proto

生成的.pyi存根文件会有正确的枚举类型定义，文档工具就能准确识别了。

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