Literal blocks not correctly generated for html

Christian Ziemski avatarChristian Ziemski created an issue

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.

Comments (4)

  1. Christian Ziemski

    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?

  2. Christian Ziemski
    • changed status to open

    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+)

  3. Log in to comment
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.