格式化 reStructuredText 中链接中的文本

Posted 2023-02-24

【中文标题】格式化 reStructuredText 中链接中的文本

【英文标题】：Format text in a link in reStructuredText

【发布时间】：2011-06-12 05:53:37

【问题描述】：

如何在 reStructuredText 中指定链接中设置文本格式？

具体来说，我希望从我的第一个 html 中生成以下 HTML：

<a href="http://docs.python.org/library/optparse.html"><tt>optparse.OptionParser</tt> documentation documentation</a>

结果应该是这样的：

optparse.OptionParser documentation

其中“optparse.OptionParser”部分是固定宽度字体。

我试过了

```optparse.OptionParser`` <http://docs.python.org/library/optparse.html>`_

但是，这给了

<tt class="docutils literal">`optparse.OptionParser</tt> documentation &lt;<a class="reference external" href="http://docs.python.org/library/optparse.html">http://docs.python.org/library/optparse.html</a>&gt;`_

看起来像这样

``optparse.OptionParser documentation <http://docs.python.org/library/optparse.html>\_

【参考方案1】：

这个结构：

Here you have |optparse.OptionParser|_.

.. |optparse.OptionParser| replace:: ``optparse.OptionParser`` documentation
.. _optparse.OptionParser: http://docs.python.org/library/optparse.html

生成此 HTML（添加了一些换行符）：

<p>Here you have 
  <a class="reference external" href="http://docs.python.org/library/optparse.html">
  <tt class="docutils literal"><span class="pre">optparse.OptionParser</span></tt> documentation</a>.
</p>

我意识到这不是完全您所要求的，但也许它已经足够接近了。另见http://docutils.sourceforge.net/FAQ.html#is-nested-inline-markup-possible。

【讨论】：

这真的很漂亮。我一直在寻找各种过度设计的解决方案，包括在我发现这个之前编写自定义扩展。

这不真的很漂亮。这太可怕了。所有理智的标记语言都支持内联标记的无限嵌套，因为这是 2016 年。自 1959 年以来，上下文无关解析已被简单地解决。（Chomsky："On certain formal properties of grammars."）reStructuredText 解析器无法执行真正的上下文无关的解析是一个粗鲁、丑陋的瑕疵。 reST 定义明确且高度可扩展的语法值得更好。 （应该有人为此感到难过。）

FAQ 条目中的"details here" link 很有趣……尤其是“如果明确，其他形式的内联标记可以嵌套”；我想知道它是否会发生的唯一方法是，如果有人只是尝试制作一个补丁集来处理明确的情况，然后这个"slightly out-of-spec" flavor of RST becomes commonplace 足以让一切都从那里滚雪球（或者至少我们得到了很好的支持立即用于明确的情况）

请注意，这仅适用于超链接，不适用于文档内链接（如 :ref:）

【参考方案2】：

你试过intersphinx吗？使用该扩展，以下标记：

:py:class:`optparse.OptionParser`

生成此 HTML：

<a class="reference external" href="http://docs.python.org/2.6/library/optparse.html#optparse.OptionParser" title="(in Python v2.6)"><tt class="xref py py-class docutils literal"><span class="pre">optparse.OptionParser</span></tt></a>

使用 Python 2.6 和 Sphinx 1.0.5 测试。

【讨论】：

啊，好吧，我不知道 intersphinx。谢谢，很高兴知道。 optparse 的链接实际上只是一个示例。我真的很关心任何 URI 链接中的文本格式。

【参考方案3】：

取自 mzjn 引用的同一常见问题解答页面：

The "raw" directive can be used to insert raw HTML into HTML output:

Here is some |stuff|.

.. |stuff| raw:: html

   <em>emphasized text containing a
   <a href="http://example.org">hyperlink</a> and
   <tt>inline literals</tt></em>

理论上应该可以用 RST 做不了的事情来做复杂的事情。

【讨论】：

这行得通，但它也破坏了其他作家（LaTeX、PDF 等）

【参考方案4】：

如果你想从本质上获得 HTML/CSS 等价物

<span class="red">This is red text</span>

在使用 Sphinx 的 reStructuredText 中，您可以通过创建角色来做​​到这一点：

.. role:: red

然后你这样使用它：

:red:`This is red text`

上面一行的末尾应该只有一个刻度线`。 当然，你必须有

.red  color: red 

在您的 CSS 文件中。