restructuredtext - Sphinx issues mysterious error in literal blocks

Question

In Sphinx (the ReStructuredText publishing system), are there any obscure rules that limit what a literal block can contain?

Background: My document contains many literal blocks that follow a double-colon paragraph, like this:

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

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

This block (with a different preceding paragraph) is one of the ones that issues an error: "WARNING: Inconsistent literal block quoting." The message indicates that the error is in the "echo" line. In the HTML output the literal block contains only the "sudo" line; the "echo" line is treated as ordinary text.

I haven't been able to identify any common property in the lines that report errors, or anything that distinguishes them, as a class, from lines in other literal blocks that don't get errors.

question from:https://stackoverflow.com/questions/65925967/sphinx-issues-mysterious-error-in-literal-blocks

Answer 1

I stripped down the project to isolate the problem, and I identified it that way.

I had a numbered list item that contained a double-colon literal block that was indented only as far as the list item's text, like this:

2. Set up the... directory::

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

When I indented the literal block further, the problem went away.

I was misled by two things:

1. The message does not point to the first line in the literal block, but to some apparently random line within it. In the case above, it pointed to the fifth line (out of eight) in the block!

2. In most cases this form of indention, although incorrect, works just fine.

Isolating the problem is a brute-force method of solving it, but is often effective when deduction fails. I'll keep that in mind in the future.