如何为pybind11导出的Python模块添加文档并在PyCharm中查看，以及将C++ Doxygen注释转换为Python文档

一、手动为pybind11导出的模块/类/函数添加文档 #

你已经在py::def的第三个参数里尝试添加了简单文档，这是基础方向。要让PyCharm能识别更完整的提示（比如参数说明、返回值），需要遵循Python标准的docstring格式（Google、NumPy或reStructuredText风格均可），PyCharm会自动解析这些格式的内容。

修改你的pybind11代码，补充更规范的文档字符串：

PYBIND11_MODULE(module, m) {
    // 模块级文档
    m.doc() = "My Library Python Bindings: 用于管理宽度属性的简单模块";

    // 类级文档
    py::class_<A>(m, "A", "封装宽度属性的类，提供宽度获取方法")
        // 构造函数文档
        .def(py::init<>(), "初始化一个默认宽度为0的A实例")
        // 函数文档：用Google风格明确返回值说明
        .def("GetWidth", &A::GetWidth, "获取当前实例的宽度值\n\n返回：\n    int: 实例的宽度数值");
}

这样修改后，当你在PyCharm中调用A()或a.GetWidth()时，就能看到对应的提示信息。

二、自动将C++ Doxygen注释转换为Python文档 #

如果你已经在C++代码中写了大量Doxygen格式的注释，完全可以自动同步到Python模块，不用手动重复编写，推荐两种方案：

1. 利用pybind11原生的Doxygen文档提取功能

pybind11支持直接从Doxygen生成的XML文件中提取注释，作为Python模块的docstring，步骤如下：

• 首先配置Doxygen：在你的Doxyfile中开启XML输出，设置GENERATE_XML = YES，然后运行Doxygen生成XML格式的文档。
• 编译模块时启用pybind11的Doxygen解析：在编译脚本（比如CMakeLists.txt）中定义PYBIND11_DOCSTRING_FROM_DOXYGEN宏，让pybind11自动读取Doxygen XML文件并映射注释。
  示例CMake配置：

  # 生成Doxygen XML文档
  find_package(Doxygen REQUIRED)
  set(DOXYGEN_GENERATE_XML YES)
  doxygen_add_docs(doxygen_docs ${PROJECT_SOURCE_DIR}/include COMMENT "生成Doxygen XML格式文档")
  
  # 编译pybind11模块并启用Doxygen注释提取
  pybind11_add_module(module MODULE your_source.cpp)
  target_compile_definitions(module PRIVATE PYBIND11_DOCSTRING_FROM_DOXYGEN)
  # 确保模块能访问到Doxygen生成的XML文件，也可以通过额外配置将XML嵌入到二进制中
  

  这样你的C++函数GetWidth上的Doxygen注释会自动被提取为Python函数的docstring。

2. 生成Python Stub文件（.pyi）

PyCharm对C扩展模块的代码提示高度依赖Stub文件（.pyi），这是一个纯Python格式的"接口描述文件"，只包含类、函数的签名和文档，没有实际逻辑。你可以用工具自动生成：

• 使用pybind11-stubgen工具：这是专门为pybind11模块设计的Stub生成工具，能自动解析你的C扩展模块，生成符合规范的Stub文件，还能自动提取Doxygen注释。
  安装：pip install pybind11-stubgen
  使用：pybind11-stubgen -o stubs your_module_name
• 把生成的Stub文件放在你的模块所在目录，或者在PyCharm的Settings > Project: XXX > Python Interpreter中添加Stub文件的路径，PyCharm就会自动读取Stub中的文档，给你提供和OpenCV一样的代码提示体验。

生成的Stub文件示例（module.pyi）：

class A:
    def __init__(self) -> None:
        """Initialize an A instance with default width 0"""
        ...
    def GetWidth(self) -> int:
        """
        @brief explanation from c++
        Get the current width value
        
        Returns:
            int: The width of the instance
        """
        ...

三、PyCharm识别文档的注意事项 #

1. 更新Stub文件：如果修改了C++代码的注释或函数签名，记得重新生成Stub文件，PyCharm才能获取最新的提示。
2. 规范docstring格式：不管手动写还是自动生成，尽量用Google/NumPy/reStructuredText风格的docstring，PyCharm对这些格式的解析最完善。
3. 模块路径配置：确保你的自定义模块在PyCharm的Python解释器路径中，否则PyCharm无法识别模块，更别提文档提示了。

备注：内容来源于stack exchange，提问作者Qiang Zhang