如何在 ReST 中处理两个破折号答案

【问题标题】：How to handle two dashes in ReST如何在 ReST 中处理两个破折号
【发布时间】：2013-03-06 21:53:55
【问题描述】：

我正在使用 Sphinx 来记录一个用 Python 编写的命令行实用程序。我希望能够记录一个命令行选项，例如--region，如下所示：

**--region**  <region_name>

在 ReST 中，然后使用 Sphinx 为我生成 HTML 和手册页。

这在生成手册页时效果很好，但在生成的 HTML 中，-- 变成了-，这是不正确的。我发现如果我将源 ReST 文档更改为如下所示：

**---region**  <region_name>

HTML 生成正确，但现在我的手册页有 --- 而不是 --。也不正确。

我尝试使用反斜杠字符（例如 \-\-）转义破折号，但没有效果。

任何帮助将不胜感激。

【问题讨论】：

我发现一个简单的解决方案是将双连字符包含在代码标记中，例如``--region`` 而不是 **--region**。可能有更优雅的方法来解决它，但这对我有用。
也许你可以使用一个选项列表：docutils.sourceforge.net/docs/ref/rst/…
是的，这似乎有点合适。谢谢，一直在发现 ReST 中的新事物！

标签： python-sphinx restructuredtext

【解决方案1】：

在 Sphinx 1.6 html_use_smartypants has been deprecated 中，不再需要在 conf.py 中设置 html_use_smartypants = False 或作为 sphinx-build 的参数。相反，您应该使用smart_quotes = False。

如果您想使用以前由html_use_smartypants 提供的转换，建议改用smart_quotes，例如smart_quotes = True。

请注意，在撰写本文时，请阅读文档引脚 sphinx==1.5.3，它不支持 smart_quotes 选项。在此之前，您需要继续使用html_use_smartypants。

编辑看来，Sphinx 现在使用 smartquotes 而不是 docutils smart_quotes。 h/t @bad_coder。

【讨论】：

读者注意，语法已更改为smartquotes = False。正是这种单行配置为我解决了双破折号-- 问题。

【解决方案2】：

有

**-\\-region**  <region_name>

它应该可以工作。

【讨论】：

【解决方案3】：

这是 Sphinx 中默认启用的配置选项：html_use_smartypants 选项 (http://sphinx-doc.org/config.html?highlight=dash#confval-html_use_smartypants)。

如果您关闭该选项，则必须使用 Unicode 字符“-”如果您想要一个破折号。

【讨论】：

这当然是一种解决方法。我认为这种行为是错误，因为首先用 endash 替换 '--' 并在 '---' 之后用 emdash 替换并不是那么难。
在这个功能的意义上，例如:command:`sphinx-build --version` 产生一个“印刷正确”的命令行：sphinx-build —–version...

【解决方案4】：

要添加两个破折号，请添加以下内容：

.. include:: <isotech.txt>

|minus|\ |minus|\ region

注意反斜杠和空格。这样可以避免在减号和参数名称之间有空格。

您只需在每页中包含一次isotech.txt。

使用此解决方案，您可以保留扩展 smartypants 并在您需要的文本的每个部分写两个破折号。不只是在选项列表或文字中。

【讨论】：

【解决方案5】：

正如@mzjn 所说，解决原始提交者需求的最佳方式是使用Option Lists。

格式很简单：以-、--、+ 或/ 开头的一系列行，后跟实际选项，（至少）两个空格，然后是选项说明：

-l     long listing
-r     reversed sorting
-t     sort by time
--all  do not ignore entries starting with .

选项和描述之间的空格数可能因行而异，至少需要两个，这样可以清楚地显示源代码（如上）以及生成的文档。

选项列表也具有选项参数的语法（只需在两个空格之前添加一个或多个包含在<> 中的单词）；有关详细信息，请参阅链接页面。

此页面上的其他答案针对原始提交者的问题，这个解决了他们的实际需求。

【讨论】：