将Python方法迁移到PyO3 Rust扩展后，如何维持Sphinx自动文档功能？

方法1：手动为导入的函数补充元信息 #

在mymod.py里导入func后，手动补全它的文档字符串，并修正模块归属，让Sphinx把它当成当前模块的成员处理：

# mymod.py
from .mymod_rs import func

# 直接复用Rust端写好的文档，或者复制过来
func.__doc__ = """这是func函数的功能说明
参数：
- arg1: xxx类型，作用xxx
返回值：xxx类型，含义xxx
"""
# 修正模块归属，让Sphinx识别为当前模块的函数
func.__module__ = __name__

这样automodapi就能正常抓取这个函数，生成文档和交叉引用。

方法2：修改Sphinx配置扩展autodoc行为 #

在conf.py里开启文档继承，并添加自定义逻辑让Sphinx处理导入的对象：

# conf.py
autodoc_inherit_docstrings = True

def setup(app):
    from sphinx.ext.autodoc import FunctionDocumenter
    # 让文档器识别导入自Rust扩展的func
    FunctionDocumenter.add_parent('mymod.mymod_rs.func')

如果Rust端已经通过PyO3的#[doc]属性写了函数文档，这个配置会自动继承这些内容，不用手动复制。

方法3：在RST文档中手动关联Rust扩展的函数 #

不想修改Python模块的话，可以直接在.rst文件里单独生成Rust扩展中func的文档，再在原模块文档里做交叉引用：

# 先单独生成Rust扩展函数的文档（加:noindex:避免重复索引）
.. automodule:: mymod.mymod_rs
   :members: func
   :noindex:

# 然后在mymod的文档里添加说明和交叉引用
`mymod.func` 已迁移至Rust扩展实现，功能与原版本一致，详情见 :func:`mymod.mymod_rs.func`

这种方式适合需要明确告知用户迁移情况的场景，同时保留交叉引用能力。

方法4：用存根模块+Mock解决构建环境问题 #

如果构建文档时Rust扩展无法正常导入（比如环境依赖问题），可以创建存根模块配合Sphinx的Mock功能：

1. 在文档目录下创建存根文件docs/stubs/mymod/mymod_rs.py：

def func(arg1, arg2):
    """这是func函数的功能说明"""
    pass

2. 在conf.py里添加配置：

import sys
from pathlib import Path
# 把存根目录加入路径
sys.path.insert(0, str(Path(__file__).parent / "stubs"))

# Mock真实的Rust扩展模块
autodoc_mock_imports = ["mymod.mymod_rs"]

这样Sphinx构建时会用存根模块的内容生成文档，原Python模块的导入也能被正常识别。

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