Literal blocks not correctly generated for html #1180
Description
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