Included code is not properly displayed

[loebl]

Problem

When including code files via .. include they are rendered as one long line, instead of the expected block.

Reproducible Project

Compare:

External file main.cpp

#include <stdio>

int main()
{
  std::cout << "hello\n";
  return 0;
}

.. include:: main.cpp
  :code: cpp
  :number-lines:

versus

.. code:: cpp

  #include <stdio>

  int main()
  {
    std::cout << "hello\n";
    return 0;
  }

Error Logs/Results

The difference between included code and code blocks in the html are:

• included: <pre class="code cpp literal-block"><code>...content..</code></pre>
• code block: <div class="highlight-cpp notranslate"><div class="highlight"><pre>..content..</pre></div></div>

Additionally included blocks use different CSS classes for highlighting. For example:

• included: literal scalar plain
• code block: l l-Scalar l-Scalar-Plain

In summary this seems to create a bit of unnecessary duplicates for the style sheets.

Expected Results

included code and code blocks should look the same.

Environment Info

(virtualenv on debian stretch)

• Python Version: 3.5.3
• Sphinx Version: 2.4.4
• docutils Version: 0.16
• RTD Theme Version: 0.4.3
• Browser: Firefox 68.8.0esr

[stsewd]

I think this may be related to sphinx, can you reproduce with the latest version of sphinx? Also with other themes?

[loebl]

Just updated my sphinx and ran the tests again. (output of pip3 list shortened to most relevant packages)

Package                       Version
----------------------------- ---------
alabaster                     0.7.12
docutils                      0.16
Jinja2                        2.11.2
Pygments                      2.6.1
Sphinx                        3.2.1
sphinx-rtd-theme              0.5.0

It seems related to the number-lines option. Updated minimal example:

.. include:: main.cpp
   :code: cpp
   :number-lines:

.. include:: main.cpp
   :code: cpp

I run sphinx for these tests with the following command:

sphinx-build -b singlehtml -C -D "master_doc=test" \
	-D 'extensions=sphinx_rtd_theme' -D 'html_theme=sphinx_rtd_theme' . _build

With default (alabaster) theme the first segment (with numbered lines) is shown with multiple lines but has no colored highlighting. The second on has colored highlighting. So this is fine.

With RTD 0.5 The first one is a single line and no colored highlighting. The second one is shown as expected, with colored highlighting. So no change here, still not looking as expected.

I took a look around with the firefox developer tools. The CSS property white-space is set to nowrap (from selector .rst-content code, code). Disabling this sets it to pre giving a multiline appearance as expected.

The coloring is a different issue due to the mentioned different CSS classes as mentioned before. But this is probably more related to docutils/pygments and not sphinx or the theme.

[Blendify]

If you want syntax highlighting you need to use a literalinclude. #1087 will fix the wrapping issue.

[loebl]

Is there already a date for the next release with this fix? I recognize this is only a minor issue, but just in case a release is already planned, it's nice to know when to update my build environment.

[Blendify]

My pr fixes the issue but it creates new ones so I still need to put in some work to fix this issue. We want to have a new release somewhat soon but it's hard to give a date.