1

While developing a Python package I am working on a Sphinx documentation with a ReadTheDocs theme which I will later publish on my GitHub Pages.

My problem is that I would like to include the content of another (plaintext) file into a .rst file but have the lines wrapped.

I found a very similar question already asked and answered.
How to wrap a long literal block in reStructuredText?
I have tried out the accepted answer but it does not work for me... or maybe I am doing it wrong...
I was following this article.

Being explicit:
I have the following section in the conf.py:

# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['_static']

html_css_files = [
    'custom.css',
]

And I added custom.css under _static which contains 3 lines:

pre {
    white-space: pre-wrap;
}

The problem emerges when I try to include an MIT license text (which is in a LICENSE file in the root of the repository) into one of the .rst files:

.. literalinclude:: ../../LICENSE
   :language: text

I would like to get an effect like here:
https://snakemake.readthedocs.io/en/stable/project_info/license.html

However, in my case the text is not wrapped and there is a horizontal scroll bar at the bottom of the text block, like in the screenshot below:

enter image description here

It must be possible somehow since snakemake developers achieved it for their docs, I just don't know - how(?)

Reply to Steve's comment below: I don't think my code was applied - I inspected the source behind the built web page and the only element with pre is:

<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>Copyright 2021 ***

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the &quot;Software&quot;), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED &quot;AS IS&quot;, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
</pre></div>

On top of the source the only css loading are:

  <link rel="stylesheet" href="../_static/css/theme.css" type="text/css" />
  <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />

So my file is not there too...

maciek
  • 1,807
  • 2
  • 18
  • 30
  • It should work. Inspect the rendered HTML using developer tools. Does the custom style get loaded? Inspect the `
    ` element and see what styles actually get applied and by which `.css` file.
     – Steve Piercy Apr 07 '21 at 07:50
  • @StevePiercy, I have updated my question according to your suggestions, could you please take a look? – maciek Apr 09 '21 at 23:01
  • The HTML is good. Does `custom.css` get copied into the build's `_static` directory? Are you using at Sphinx>=1.8? Both the recommended and an alternate method are described in the [RTD theme's docs](https://docs.readthedocs.io/en/stable/guides/adding-custom-css.html). Finally do a `make clean` then `make build`. Otherwise I am stumped. – Steve Piercy Apr 10 '21 at 07:34
  • @StevePiercy: I did `make clean` and `make html` - no change. Yes, `custom.css` gets copied under `build/html/_static`. It is alongside the `pygments.css` which gets loaded, though. Sphinx v.3.5.3. I am trying only the first option from the documentation since I don't know how to fully replace the ReadTheDocs theme... How could I try it? – maciek Apr 10 '21 at 12:07
  • Check that the browser is not aggressively caching an old version of the CSS file by loading it directly in the browser and force refresh. Does its content include your custom style declarations? If it does, then use your browser's Developer Tools to determine where you custom style is loaded and gets overridden by another style declaration. – Steve Piercy Apr 11 '21 at 05:42
  • @StevePiercy: I'm sorry, I don't understand these suggestions, I am not a web developer... I use Chrome. However, I have tried now two other browsers: Safari and Firefox and the problem persists. – maciek Apr 11 '21 at 10:04
  • See https://developer.chrome.com/docs/devtools/ Unfortunately there is nothing more I can do without looking at the actual HTML and CSS files that are generated. – Steve Piercy Apr 12 '21 at 06:39

2 Answers2

1

I have the same problem using the same RTD theme, and here's how I fixed it:

pre {                                 
    white-space: pre-wrap !important; 
    word-break: break-all;            
}

The rest is as you describe in the question.

My guess is that the theme has more-specific selectors which override the very general pre selector. That's why the !important notation is required.

In addition, I also put word-break: break-all, otherwise text gets broken only on spaces or other delimiters, and some items end up showing very weirdly on the output.

I wonder why this is not an option on the theme.

caxcaxcoatl
  • 8,472
  • 1
  • 13
  • 21
0

I wanted to achieve the effect as for the snakemake documentation.
After closer inspection I noticed that their LICENSE file contains custom line breaks by itself; including such file into the .rst indeed results in a nicely "wrapped" text (i.e. no horizontal slider). So, there is no need for any css styling at all.

maciek
  • 1,807
  • 2
  • 18
  • 30