如何使用stubgen的--doc-path参数优化USD库存根类型信息？

问题背景 #

我用stubgen为Pixar的USD库生成了.pyi存根文件，但生成的存根中函数参数和返回值都用Any占位（示例如下），希望通过--doc-path参数获取更精准的类型信息。目前已用Doxygen生成了USD的HTML文档、XML文档以及C++头文件，但stubgen要求--doc-path参数传入RST格式文档，不清楚能否直接将Doxygen HTML转成RST使用。

当前生成的存根示例：

from typing import Any, ClassVar

import Boost.Python
import pxr.Ar
__MFB_FULL_PACKAGE_NAME: str

class DefaultResolver(pxr.Ar.Resolver):
    @classmethod
    def __init__(cls, *args, **kwargs) -> None: ...
    def SetDefaultSearchPath(self, *args, **kwargs) -> Any: ...
    @classmethod
    def __reduce__(cls) -> Any: ...

class DefaultResolverContext(Boost.Python.instance):
    @classmethod
    def __init__(cls, *args, **kwargs) -> None: ...
    @classmethod
    def GetSearchPath(cls, *args, **kwargs) -> Any: ...
    @classmethod
    def __eq__(cls, other) -> Any: ...
    @classmethod
    def __hash__(cls) -> Any: ...
    @classmethod
    def __ne__(cls, other) -> Any: ...
    @classmethod
    def __reduce__(cls) -> Any: ...

核心结论 #

不能直接将Doxygen生成的HTML转换为RST给stubgen的--doc-path参数使用。HTML是面向展示的格式，转成RST后只能保留文本内容，无法提供stubgen需要的结构化类型信息（比如参数类型、返回值类型的明确标注），stubgen无法从中提取有效信息来优化存根。

可行解决方案 #

1. 直接解析C++头文件补全存根 #

USD的Python绑定是从C++代码自动生成的，头文件中包含完整的类型定义，这是最可靠的类型信息来源：

• 用C++头文件解析工具（比如cppheaderparser）批量提取函数的参数类型、返回值类型
• 编写简单脚本，将现有存根中的*args, **kwargs和Any替换为从头文件中提取的实际类型
• 注意区分Boost.Python绑定的特殊语法（比如类继承、静态方法标识），确保存根符合Python类型规范

2. 基于Doxygen XML生成符合要求的RST #

Doxygen生成的XML是结构化格式，包含完整的类型元数据，比HTML更适合处理：

• 编写脚本解析XML文件，提取每个函数/类的名称、参数列表、返回值类型等信息
• 生成符合stubgen要求的RST文档，示例格式如下：

  .. py:class:: pxr.Ar.DefaultResolver(pxr.Ar.Resolver)
     :module: pxr.Ar
  
     .. py:function:: __init__(self, context) -> None
        初始化DefaultResolver实例。
  
     .. py:function:: SetDefaultSearchPath(self, searchPath: list[str]) -> None
        设置默认搜索路径。
  

• 生成RST文档后，用stubgen --doc-path=生成的RST目录重新生成存根，即可得到带精准类型的结果

3. 使用社区现成的USD存根 #

直接查找社区已经维护好的USD存根文件，比如在代码托管平台搜索pxr-stubs相关资源，直接复用现成的存根，省去手动处理的成本

注意事项 #

• stubgen的--doc-path仅识别包含py:function、py:class等指令的结构化RST，普通文档类RST无法被识别
• 处理USD存根时，要注意Boost.Python绑定的特殊性，比如类的继承关系、静态方法与实例方法的区分，避免生成不符合实际使用的存根

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