Python 模块参考与 Sphinx 文档

Question

Let's considere the following function :

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

When I compile it with sphinx-build, I have the following error :

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

It looks like the sphinx-builder is unable to understand the tag :py:module: .

What is the tag used for referencing a module in Sphinx ?

Answer 1

According to the documentation , you should use :py:mod: to cross-reference.

Generally the shorter versions of tags seem to be used to cross-reference, and longer names to document.