reStructuredText 中的缩写 (abbr) 元素答案

【问题标题】：Abbreviation (abbr) element in reStructuredTextreStructuredText 中的缩写 (abbr) 元素
【发布时间】：2016-01-07 01:14:08
【问题描述】：

如何在 ReST 中生成<abbr> 缩写元素？

<abbr title="Hypertext Markup Language">HTML</abbr>

documentation 表示“缩写元素不会在默认重组文本中公开。它只能通过自定义角色访问。”我不确定如何创建这样一个自定义角色，the rest of the 文档对我来说有点晦涩。

【问题讨论】：

您提到的abbreviation 角色为我工作（如`HTML`:abbreviation:），尽管是通过Sphinx 而不是香草Docutils。但是，似乎没有办法添加title 属性。

【解决方案1】：

对于 Sphinx 用户，可以使用:abbr: 角色添加缩写。例如，

This :abbr:`SDP (Software Development Plan)` defines ...

生成以下 HTML

<p>This <abbr title="Software Development Plan">SDP</abbr> defines …</p>

【讨论】：

【解决方案2】：

我现在通过在文档底部添加这个来解决它：

.. |HTMLabbr| raw:: html

  <abbr title="Hypertext Markup Language">HTML</abbr>

然后在文档中我使用了这个“标签”/自定义角色，如下所示：

This document is written in |HTMLabbr| and renders nicely in a modern browser.

对于每个缩写，您都必须定义一个新的自定义角色，我想知道是否有一种方法可以让“标签”将值和标题作为参数，而不必像这样硬编码这个。

【讨论】：

【解决方案3】：

创建自定义 docutils rst 角色并不难（与如何扩展 docutils 的其他方式相比）。请参阅rst roles howto，其中包含所有详细信息以及示例 RFC 角色的完整实现。我能够根据此文档创建自定义 bugzilla referencing role。

【讨论】：