Python 带有 Sphinx 文档的模块参考

Question

让我们考虑以下函数：

def format_send_event(self, message_identifier, payload=""):
    """
    Format a SendEvent.

    :param message_identifier: Message identifier (defined in the :py:module:`MyModule.constants` file).
    :type message_identifier: int
    :param payload: Payload of the message.
    :type payload: str
    """
    # Do something

当我使用 sphinx-build 编译时，出现以下错误：

...MyModule/handlers.py:docstring of MyModule.handlers.MyClass.format_send_event:3: ERROR: Unknown interpreted text role "py:module".

sphinx-builder 似乎无法理解标签 :py:module:。

在 Sphinx 中用于引用模块的标签是什么？

Answer 1

根据documentation，你应该使用:py:mod:来交叉引用。

一般来说，较短版本的标签似乎用于交叉引用，较长版本的标签用于记录。

Python 带有 Sphinx 文档的模块参考

Python module reference with Sphinx documentation

python

python-sphinx