使用 Sphinx 转换为 HTML 时如何在 reStructuredText 中转义单引号

Question

对于我正在编写的文档项目，我需要包含一个带有日期格式字符串的表格。现在几乎一切正常，但最后我遇到了一个小问题，我想打印一个文字 ' 引号和两个文字引号（分别在其他引号之间）。 Sphinx 将这些更改为上/下引号，这通常看起来非常整洁，但在这种特殊情况下会使文本不可读。我能想到的最好的方法是：

======   ===========   ======  =====================
``'``    Escape for            | " ``'`` hour ``'`` h" -> "hour 9"
         for text 
         Delimiter
``''``   Single                | "ss ``''`` SSS" -> "45 ``'`` 876"
         quote 
         Literal  
======   ===========   ======  =====================

这会产生所有正确的引号，但它会在前后插入额外的空格，我希望将其删除，因为该示例在语法上不正确。因此，也可以将我的问题改写为：如何在使用反引号时删除文字引号前后的多余空格。

我已经尝试过标准的逃跑方式。反斜杠无效，因为 ' 不是 reStructuredText 特殊字符。如果我删除空格，反引号 `` 将不再起作用。

带有额外空格的示例输出：

Answer 1

正如 cmets 中的其他人所提到的，Sphinx 将普通的" 变为卷曲的“ 等等的过程称为 SmartQuotes。

我不确定您是否一开始就特别想要文字，或者它们是否只是避免 SmartQuotes 的一种妥协，但是（至少）有两种方法可以在不需要使用的情况下停止 SmartQuotes文字：

1.为整个项目禁用 SmartQuotes：

如果您不想要 SmartQuotes，请添加：

smartquotes = False

致您的conf.py file

或者添加一个与conf.py同级的docutils.conf文件，内容如下：

[parsers]
smart_quotes: no

（来自this GitHub issue 的解决方案；请参阅Sphinx documentation 了解这两个设置如何交互 - TL；DR：即使在conf.py 中打开它们，在docutils.conf 中关闭也会覆盖）

2。转义你不想“聪明”的个别引用：

您可以使用双反斜杠\\ 来转义您想要直的引号，例如\\' 和\\"。所以在你的例子中，这个：

"\\'hour\\'h" -> "hour 9"
"ss\\'\\'SSS" -> "45\\'876"

会给出以下输出：

“'hour'h” -> “hour 9”
“ss''SSS” -> “45'876”

外部双引号保留为“智能”，但我认为这是您想要的行为。

（转义详情见official docutils documentation）

Answer 2

我刚刚在文档中找到了答案：

http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#inline-markup

事实证明，您可以通过在空格字符之前使用反斜杠“\”来转义空格字符。所以“\”将被渲染为“”。这对于您需要使用空格进行格式化但不希望显示该空格的情况很有用，就像我上面的问题一样。

所以解决办法是：

======   ===========   ======  =====================
``'``    Escape for            | "\ ``'``\ hour\ ``'``\ h" -> "hour 9"
         for text 
         Delimiter
``''``   Single                | "ss\ ``''``\ SSS" -> "45\ ``'``\ 876"
         quote 
         Literal  
======   ===========   ======  =====================

难读，但有效。

函数调用的内联格式的另一个例子：

**dateformat (**\ *<string,number,void>* **sourceDate,** *string* **sourceDateFormat,** *string* **returnDateFormat)**

事实证明，这是使格式正确的唯一方法（变量类型为斜体，其余为粗体，左括号和变量类型之间没有空格）。

Answer 3

好吧，不确定您认为哪些部分间距不正确，但最左边的引号在屏幕截图中没有多余的空格，这就是单引号在等宽字体中呈现的方式。至于右列，为什么不用双反引号将整个单元格括起来呢？这也扼杀了“聪明”的报价，我认为这就是你想要的。

``ss '' SSS" -> "45 ' 876"``
# could instead be this, if these were the spurious spaces
``ss''SSS -> "45'876"``

否则您无法摆脱双反引号跨度周围的间距 - 就解析器而言，它们构成一个“单词”，并且由作者来处理 之间的空格 单词。在您需要控制空格的地方，它不是“散文”，而是文字部分，整个空格重要的文本应该双反引号。

现在，如果您想在反引号部分中添加“智能”引号，我认为您需要走字符实体引用路线，但我不知道那会是什么样子- 应该在文档中。