Sphinx自动文档如果Python方法移至Rust PyO3

Question

如果我有一个Python模块和一个方法：

# mymod.py
def func(x):
    """
    Return a value.
    """
    return x

还有一个在rst文件中的Sphinx自动文档命令：

API Ref
-------

.. automodapi:: project.mymod

这样会为:meth:'project.mymod.func'生成相关的页面和可以互相链接的链接。一切都很好！

但是，如果我现在为我的Python包创建一个Rust扩展，把这个函数移到Rust中，并用PyO3构建这个扩展，我可以通过将Rust函数作为重载导入到Python模块中来保持代码的向后兼容性：

// mymod.rs
#[pymethod]
fn func(x: T) -> PyResult<T> {
    Ok(x)
}

# mymod.py
from mymodrs import func

Sphinx现在将不再自动检测这个func方法，也不会有可以互相链接的链接。我可以添加一些东西来保持Sphinx的可操作性吗？我不介意手动操作。

Answer 1

到目前为止，我找到了一种方法，可以让这个工作几乎保持相同的格式和章节一致性，做法是这样的：

当前版本

---

# mymod.py
def func(x):
    """
    Return a value

    Parameters
    ----------
    x: float
        The value

    Returns
    -------
    float
    """
    return x

# index.rst
Methods
-------

.. automodapi:: project.mymod

---

新的 Rust 版本

# mymod.py
from mymodrs import func

func.__doc__ = "Return a value"  # Needed for the description in autosummary

为 Rust 方法创建一个明确的文档文件。

# api_manual/mymod.func.rst
func
----

.. currentmodule:: mymod

.. py:method:: func(x)

   Return a value

   :param x: The value
   :param type: float

   :rtype: float

在原来的自动修改文件中链接到这个文档。

# index.rst
Methods
-------

.. autosummary::
   mymod.func

.. toctree::
   :titlesonly:
   :maxdepth: 0
   :hidden:

   api_manual/mymod.func.rst