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

Question

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

**--region**  <region_name>

在ReST中

然后使用Sphinx为我生成我的HTML和手册页。

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

**---region**  <region_name>

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

我尝试使用反斜杠字符（例如\-\-）转义短划线但是没有效果。

非常感谢任何帮助。

Answer 1

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

如果您关闭该选项，那么如果您想要一个短划线，则必须使用Unicode字符“ - ”。

Answer 2

使用

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

它应该有用。

Answer 3

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

.. include:: <isotech.txt>

|minus|\ |minus|\ region

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

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

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

Answer 4

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

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

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

Answer 5

@mzjn评论说，解决原始提交者需求的最佳方法是使用Option Lists。

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

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

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

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

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