Sphinx：rST 内联文字解释为代码？

Question

根据 Docutils，文本周围的双反引号相当于

:literal:

角色：https://docutils.sourceforge.io/docs/ref/rst/roles.html#literal

他们展示了一个例子，这些是等效的：

``text``
:literal:`text`

另外，它们有一个

:code:

角色，似乎旨在用于内联代码：https://docutils.sourceforge.io/docs/ref/rst/roles.html#code

此角色（和代码块）指令似乎被视为

<literal>

文档树元素。但我找不到任何说“所有文字都是代码”的内容。

在内联标记的 Sphinx 文档中，它说要对内联代码示例使用反引号：

https://www.sphinx-doc.org/en/master/usage/restructedtext/basics.html#inline-markup

当 Sphinx 编写 HTML 时，在我看来，它会将任何

不是 'kbd'

 的文字解释为 

code

： 

https://github.com/sphinx-doc/sphinx/blob/df3d94ffdad09cc2592caccd179004e31aa63227/sphinx/writers/html5.py#L645

因此，它使用 code 元素渲染 HTML 中双反引号包围的所有文字，例如：

<code>some text in a literal</code> 我不相信这是 Docutils 的

意图 - 看起来 Docutils 打算让所有代码都是文字，但并非所有文字都是代码。出于我的目的，我宁愿将文字呈现为我可以适当设置样式的独特内容，但不是<code>

，因为代码元素具有不适用于我的情况的附加语义含义。 （也就是说，我们将它用于许多我们想要在等宽空间中表示的东西，而这些东西

不是实际的代码。）

我想知道是否有人可以解释为什么 Sphinx 决定所有文字都是代码？ （或者我可能遗漏了什么并得出错误的结论？）

Answer 1

事实上，呈现为 HTML 的文字/代码元素（内联和块风格）的预先存在的

语义标记在视觉上看起来很相似。 当渲染为其他输出格式时，它们可能看起来不同。

如果您确实想要“代码”（无论这意味着什么），那么建议在

inline code

 或块的 

.. code-block::

 指令周围加上双反引号。  将 

:kbd:

 等角色保留用于预期目的。

也许您实际上并不想劫持预先存在的元素。 使用

.. role::

 指令声明您自己的语义元素（在页面顶部不可见，或通过 

include）：

.. role:: country

.. role:: city

然后在页面中使用这些新角色：

:city:`London`, the capital of :country:`England` and 
the :country:`United Kingdom`, is a 21st-century city
with history stretching back to Roman times.

并与

_static 文件夹中的 mystyles.css

 文件配对：

.city {
  font-family:monospace; font-weight:bold; background-color:yellow;
}
.country {
  font-family:monospace; font-weight:bold; background-color: orange;
}

可以给你想要的:

比通过完整的

扩展便宜很多。