Literal blocks not correctly generated for html

[shimizukawa]

Summary

It seems to be impossible to generate literal blocks correctly.

Dependent on the used theme sometimes it looks fine, but with another theme it's wrong,
aka partly highlighted (or to be exact: gets an background as if highlighted).

Here's what I did

I tried the combinations of the following options in (a standard) conf.py::

#1. highlight_language not defined at all
#2.
highlight_language = 'python'
#3.
highlight_language = 'none'

# A.
html_theme = 'sphinxdoc'
# B.
html_theme = 'basic'

with the following test document::

========
Testpage
========

A simple paragraph.

A literal block::

    with two 
    lines of source text

normal text

.. comment

Now a ``'.. codeblock:: python'``

.. code-block:: python

   if python = True:
       print "Yes"

The results

1) html_theme 'basic' or 'sphinxdoc' / highlight_language = 'none'

resulting html:

<p>A simple paragraph.</p>
<p>A literal block:</p>
<div class="highlight-none"><div class="highlight"><pre>with two
lines of source text
</pre></div>
</div>

with the optical results:

• basic

  wrong: Literal block gets green background as if it should be highlighted

• sphinxdoc

  wrong: Literal block gets gray background as if it should be highlighted

2) html_theme 'basic' or 'sphinxdoc' / no highlight_language or 'python'

resulting html:

<p>A simple paragraph.</p>
<p>A literal block:</p>
<div class="highlight-python"><pre>with two
lines of source text</pre>
</div>

with the optical results:

• basic

  correct: Literal block looks as expected: fixed width font, no background, no highlight (but that may be by coincidence)

• sphinxdoc

  wrong: Literal block gets gray background as if it should be highlighted

Finally

As far as I found out until now the literal block gets a wrong div class.

I think literal blocks shouldn't get any "highlight" class but some "literal" one.

In case 1) there are both nested highlight div's, but there shouldn't be any such.

Case 2) is in between:

• There's a div with class="highlight-python"
• but no additional div with class="highlight"
  as for example in the (correctly generated) code-blocks.

So in case 2 it's not a literal block but neither a correct code-block.

Tested versions

I tested the above issue with versions stable (1.1.3) and default (1.2) with the same results.

Location of the bug

Probably the

if node.rawsource != node.astext():

in HTMLTranslator.visit_literal_block() in file writers/html.py doesn't work as intended.

Since I'm new to using Sphinx (and I really like it!) I probably will be unable to fix it myself.

But I'll play a bit with the code and post followups, if possible.

---

• Bitbucket: https://bitbucket.org/birkenfeld/sphinx/issue/1180
• Originally reported by: Christian Ziemski
• Originally created at: 2013-06-01T12:39:21.362

[shimizukawa]

From Christian Ziemski on 2013-06-01 10:43:56+00:00

PS: Tickets #647 and/or #695 may be related.

[shimizukawa]

From Georg Brandl on 2014-01-12 15:07:44+00:00

This is quite probably covered by the #695 fix.

[shimizukawa]

From Christian Ziemski on 2014-02-05 19:59:44+00:00

The changes from #695 (or perhaps something else) indeed changed the results.

Now it's more consistent - but still not completely correct IMHO:

In both cases above the given class is been generated, dependent on the config value highlight_language:

First a div class="highlight-python" or "highlight-none" followed by an inner
div class="highlight".

But still a simple literal block gets a background as if it is highlighted (green background in basic style).

I would expect/hope literal blocks to get created with a fixed width font, but no special background at all.

Or am I simply wrong with this assumption?

[shimizukawa]

From Christian Ziemski on 2014-02-05 20:02:55+00:00

Simple literal blocks are still created with a colored background as if highlighted. More infos in the previous comment. (Tested with the current version 1.2.1+)

[jekriske]

We accidentally upgraded sphinx and are seeing this with 1.3.1... is there any fix? Pages look horrible.

[shimizukawa]

@jekriske it looks another issue. Please create a new ticket. Thanks.