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

问题描述

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

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

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

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

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

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

解决方法

我精简了项目以隔离问题，并以这种方式确定了它。

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

2. Set up the... directory::

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

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

我被两件事误导了：

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

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

隔离问题是解决问题的蛮力方法，但在推理失败时通常很有效。以后我会牢记这一点。