Python ReST文档字符串中是否有类似于C#的“see cref”的东西？

Question

我正在将一些C#代码转换为Python 3，其中包括通常在原始C#代码中以XML摘要形式编写的文档。

这些摘要引用了类名作为<see cref="ClassName"/>元素或<paramref name="fileName"/>元素来引用参数，当将其转换为HTML时创建可点击的链接。我想知道在我使用的Python ReST文档字符串格式中是否有类似的功能。

例如，让我们看看这个C#方法文档：

/// <summary>
/// Reads and returns a <see cref="DummyFile"/> instance from the file with the
/// given <paramref name="fileName"/>.
/// </summary>
/// <param name="fileName">The name of the file to read the data from.</param>
/// <returns>The read <see cref="DummyFile"/> instance.</returns>
public DummyFile LoadDummyFile(string fileName)
{
    // Do some dummy file work.
}

在Python中，我会将它转换为：

"""
Reads and returns a DummyFile instance from the file with the given file_name.
:param file_name: The name of the file to read the data from.
:param str file_name: The name of the file to read the data from.
:return: The read DummyFile instance.
:rtype: DummyFile
"""
def load_dummy_file(file_name: str) -> DummyFile
    # Do some dummy file work.

（有人使用:rtype吗？） 如您所见，我只是将类名和参数名输入为纯文本，不知道在创建Web文档时是否有这种特殊语法可以创建可点击链接。

在ReST docstrings中创建此类引用是否可能，如果可以，它们的语法（希望不要比C#长）是什么？

- Ray

---

像这样：https://bitbucket.org/zzzeek/sphinx-paramlinks? - denfromufa

听起来是这样，但是难道没有一个"内置"的解决方案吗？ - Ray

Answer 1

对于<see cref="ClassName">，您可以使用

:py:class:`ClassName`

这将成为指向类定义的可点击引用。请参见Sphinx Domains。

我不知道file_name是否有类似的方法。但是为什么需要一个指向下面两行位置的可点击链接呢？

我使用这个rtype指令。

- Humbalan