带有 ReadTheDocs 主题的 Sphinx 文档：文本块换行答案

【问题标题】：Sphinx documentation with ReadTheDocs theme: text block wrapping带有 ReadTheDocs 主题的 Sphinx 文档：文本块换行
【发布时间】：2021-04-06 15:07:17
【问题描述】：

在开发 Python 包时，我正在编写带有 ReadTheDocs theme 的 Sphinx 文档，稍后我将在我的 GitHub 页面上发布该文档。

我的问题是我想将另一个（纯文本）文件的内容包含到 .rst 文件中，但将行换行。

我发现一个非常相似的问题已经被问及并得到了回答。
How to wrap a long literal block in reStructuredText?
我已经尝试了接受的答案，但它对我不起作用......或者我做错了......
我在关注this article。

明确：
我在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',
]

我在 _static 下添加了 custom.css，其中包含 3 行：

pre {
    white-space: pre-wrap;
}

当我尝试将 MIT 许可证文本（位于存储库根目录的 LICENSE 文件中）包含到 .rst 文件之一时，问题出现了：

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

我想得到这样的效果：
https://snakemake.readthedocs.io/en/stable/project_info/license.html

但是，在我的例子中，文本没有换行，文本块底部有一个水平滚动条，如下面的屏幕截图所示：

这一定是可能的，因为 snakemake 开发人员为他们的文档实现了它，我只是不知道 - 如何（？）

在下面回复史蒂夫的评论：我不认为我的代码被应用了 - 我检查了构建网页背后的源代码，唯一带有 pre 的元素是：

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

在源代码之上，唯一的 css 加载是：

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

所以我的文件也不在那里......

【问题讨论】：

它应该可以工作。使用开发人员工具检查呈现的 HTML。自定义样式是否被加载？检查<pre> 元素并查看实际应用了哪些样式以及哪个.css 文件。
@StevePiercy，我根据你的建议更新了我的问题，你能看看吗？
HTML 很好。 custom.css 是否被复制到构建的 _static 目录中？您在 Sphinx >=1.8 上使用吗？ RTD theme's docs 中描述了推荐的方法和替代方法。最后做一个make clean 然后make build。否则我难住了。
@StevePiercy：我做了make clean 和make html - 没有变化。是的，custom.css 被复制到 build/html/_static 下。不过，它与已加载的pygments.css 并排。狮身人面像 v.3.5.3。我只尝试文档中的第一个选项，因为我不知道如何完全替换 ReadTheDocs 主题......我该如何尝试？
通过直接在浏览器中加载旧版本的 CSS 文件并强制刷新来检查浏览器是否没有主动缓存旧版本的 CSS 文件。它的内容是否包括您的自定义样式声明？如果是，则使用浏览器的开发人员工具来确定自定义样式的加载位置并被另一个样式声明覆盖。

标签： python-sphinx restructuredtext read-the-docs

【解决方案1】：

我想达到 snakemake 文档的效果。
经过仔细检查，我注意到他们的 LICENSE 文件本身包含自定义换行符；将此类文件包含在 .rst 中确实会产生一个很好的“包装”文本（即没有水平滑块）。因此，根本不需要任何 css 样式。

【讨论】：

【解决方案2】：

我在使用相同的 RTD 主题时遇到了同样的问题，我是这样解决的：

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

其余的如你在问题中描述的那样。

我的猜测是主题有more-specific selectors 覆盖了非常通用的pre 选择器。这就是为什么需要 !important 符号的原因。

此外，我还输入了word-break: break-all，否则文本只会在空格或其他分隔符处被破坏，并且某些项目最终会在输出中显示得很奇怪。

我想知道为什么这不是主题的选项。

【讨论】：