Sphinx autodoc（如果 Python 方法移至 Rust PyO3）

Question

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

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

第一个文件中的 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

在原始 automod 文件中链接到它。

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

.. autosummary::
   mymod.func

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

   api_manual/mymod.func.rst