Sphinx 在文字块中发出神秘错误

Question

在 Sphinx（ReStructuredText 发布系统）中，是否有任何晦涩的规则限制文字块可以包含的内容？

背景：我的文档包含许多跟随双冒号段落的文字块，如下所示：

Background:... follow a double-colon paragraph, like this::

        $ sudo su
        # echo ttyS0,115200 > /sys/module/kgdboc/parameters/kgdboc

此块（前面有不同的段落）是发出错误的块之一：“警告：文字块引用不一致。”该消息表明错误出现在“echo”行中。在 HTML 输出中，文字块仅包含“sudo”行； “echo”行被视为普通文本。

我无法识别报告错误的行中的任何公共属性，或者将它们作为一个类与其他没有错误的文字块中的行区分开来的任何东西。

Answer 1

我剥离了项目来隔离问题，并通过这种方式识别了它。

我有一个编号列表项，其中包含一个双冒号文字块，该块仅缩进至列表项的文本，如下所示：

2. Set up the... directory::

   $ A Linux command
   $ Another Linux command 
   $ And ANOTHER Linux command
   $ etc.

当我进一步缩进文字块时，问题就消失了。

我被两件事误导了：

1. 该消息并不指向文字块中的第一行，而是指向其中的一些明显随机的行。在上面的例子中，它指向块中的第五行（共八行）！

2. 在大多数情况下，这种形式的缩进虽然不正确，但效果很好。

隔离问题是解决问题的一种暴力方法，但在演绎失败时通常是有效的。以后我会牢记这一点。

Answer 2

双冒号后面的行， 不缩进并以“标题装饰字符”开头

::

$ sudo su
# echo ttyS0,115200 > /kgdboc

被解析为引用的文字块。 该块以第一个空行结束。

引用字符必须一致。 因此，上面的例子产生 错误信息：

/tmp/qblock.rst:4：（错误/3）文字块引用不一致。

它指向引号字符不一致的行。

缩进文字块解决了这个问题，因为现在它是一个缩进文字块，其中一致行开头的约束被解除。