在 reStructuredText 中显示链接标题的一部分

问题描述

我是 Python 文档的 reStructuredText 和 Sphinx 的绝对初学者。我正在尝试使用我现有的脚本之一，一个处理创建/发送电子邮件消息的 Emailer 类，它使用 Python 的 email 库。我的其中一种方法的文档字符串（我相信是 NumPy 风格）如下：

def attach(self,msg: EmailMessage,file: BinaryIO,/,*,filename: Optional[str] = None,**kwargs) -> None:
        """Add an attachment to the :class:`~email.message.EmailMessage` msg using specified params.

        Parameters
        ----------
        msg: :class:`~email.message.EmailMessage`
            The message to add the attachment to.
        file: :class:`~typing.BinaryIO`
            The file-like object of the attachment to be added,opened in binary mode.
        filename: Optional[:class:`str`]
            The name to use for the attachment. Defaults to ``None``,using ``file.name``.
        **kwargs
            Additional kwargs that would be passed to :meth:`~email.message.EmailMessage.add_attachment`.
        """

我的问题是，如何才能使 **kwargs 的描述显示为：

将传递给 EmailMessage.add_attachment()

的其他 kwargs

~ 运算符使它只显示 add_attachment()，如果我使用 :meth:EmailMessage.add_attachment，链接根本无法生成（显然我需要指定完整的来源 { {1}}？）

另一方面，我会很感激一些关于语法/约定的指针。例如，考虑到它们已在文档字符串中描述，我是否应该删除方法签名中的类型提示？另外，如何从结果文档中排除某些属性/方法？谢谢。

解决方法

以下标记有效：

:meth:`EmailMessage.add_attachment() <email.message.EmailMessage.add_attachment>`

来自https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#cross-referencing-syntax：

您可以提供明确的标题和引用目标，例如在 reST 直接超链接中：
:role:`title <target>` 将引用 target，但链接文本将是 title .

此处描述了“直接超链接”：https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html?highlight=hyperlinks#external-links。

python-3.x python-sphinx restructuredtext