如何解决在 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`.
"""
将传递给 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。
版权声明:本文内容由互联网用户自发贡献,该文观点与技术仅代表作者本人。本站仅提供信息存储空间服务,不拥有所有权,不承担相关法律责任。如发现本站有涉嫌侵权/违法违规的内容, 请发送邮件至 dio@foxmail.com 举报,一经查实,本站将立刻删除。