Question

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

这些摘要将类名引用为<see cref="ClassName"/>元素或<paramref name="fileName"/>元素，用于引用参数，例如在将其转换为HTML时创建可点击链接。我想知道我使用的Python ReST docstring格式是否有类似的东西。

例如，让我们来看看这个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文档字符串中创建这样的类引用，如果是，那么它们的可能性（希望比C＃更长）是什么？

Answer 1

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

：吡啶：类：`ClassName`

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

我不知道file_name的任何类似方法。但是你需要一个可点击的链接到下面的地方拖线？

我使用此 rtype 指令。

有没有像C＃＆＃34;＆＃34;看到cref＆＃34;在Python ReST docstrings中？

1 个答案: