在 reStructuredText 中显示部分 link 标题

Question

我是 Python 文档的 reStructuredText 和 Sphinx 的绝对初学者。我正在尝试使用我现有的一个脚本，一个处理 creating/sending 电子邮件消息的 Emailer class，它使用 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 的描述显示为：

Additional kwargs that would be passed to EmailMessage.add_attachment()

~ 运算符使得只有 add_attachment() 出现，如果我使用 :meth:EmailMessage.add_attachment，link 根本无法生成（显然我需要指定完整的来源 email.message.<foo>?)

另一方面，我希望得到一些关于 syntax/convention 的指点。例如，考虑到它们已经在文档字符串中描述，我是否应该删除方法签名中的类型提示？另外，如何排除某些 attributes/methods 出现在生成的文档中？谢谢。

Answer 1

以下标记有效：

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

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

You may supply an explicit title and reference target, like in reST direct hyperlinks:
:role:`title <target>` will refer to target, but the link text will be title.

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

在 reStructuredText 中显示部分 link 标题

Displaying a portion of the link caption in reStructuredText

python-3.x

python-sphinx

restructuredtext