在 reStructuredText 中显示部分链接标题答案

【问题标题】：Displaying a portion of the link caption in reStructuredText在 reStructuredText 中显示部分链接标题
【发布时间】：2021-08-29 11:04:11
【问题描述】：

我是 reStructuredText 和 Sphinx for Python 文档的绝对初学者。我正在尝试我现有的一个脚本，一个处理创建/发送电子邮件的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，则根本无法生成链接（显然我需要指定完整的来源email.message.<foo>？）

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

【问题讨论】：

我怀疑它试图突出显示那些~~~ 的一行。当您转义该字符 \~ 时，您是否有更好的结果？
要链接到另一个项目，请使用 intersphinx：sphinx-doc.org/en/master/usage/extensions/…
@mzjn 我的conf.py 中已经有了intersphinx_mapping = {'python': ('https://docs.python.org/3.9', None)} 这一行。我的问题是如何使 EmailMessage.add_attachment() 显示为标题，而没有“email.message”。在它之前。
@Doyousketch2 在~ 之前添加反斜杠没有任何作用。也没有像~~这样连续放置波浪号。

标签： python-3.x python-sphinx restructuredtext

【解决方案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。

【讨论】：

这行得通！小提示：我需要使用此语法在标题后添加明确的()。感谢您的帮助！
已添加() 回答。