reStructuredText 中的缩写（abbr）元素

Question

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

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

documentation indicates that "The abbreviation element is not exposed in default restructured text. It can only be accessed through custom roles." I'm not sure how to create such a custom role, and the rest of the 文档对我来说有点晦涩难懂。

Answer 1

我已经通过在文档底部添加以下代码解决了这个问题：

.. |HTMLabbr| raw:: html

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

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

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

对于每个缩写，您都必须定义一个新的自定义角色，我想知道是否有一种方法可以让 "tag" 将值和标题作为参数，而不必 hard-code 是这样的。

Answer 2

创建自定义 docutils 第一个角色并不难（与其他扩展 docutils 的方法相比）。请参阅 rst roles howto, which contains all the details along with a full implementation of example RFC role. I was able to create custom bugzilla referencing role 基于此文档。

Answer 3

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

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

结果如下HTML

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

reStructuredText 中的缩写（abbr）元素

Abbreviation (abbr) element in reStructuredText

restructuredtext