【问题标题】：Modifying content width of the Sphinx theme 'Read the Docs'修改 Sphinx 主题“阅读文档”的内容宽度
【发布时间】：2014-06-06 08:40:52
【问题描述】：

我正在为我的文档使用“阅读文档”Sphinx 主题。在原始主题中，如下所示

http://read-the-docs.readthedocs.org/en/latest/theme.html

内容或主要布局宽度设计为适合移动设备。但是，对于我的项目，我希望它更广泛一些。我不懂 HTML，因此如果有人能给我一些增加内容（布局）宽度的线索，我将不胜感激。

【问题讨论】：

2019 年，只需通过 html_css_files 选项添加所需的 css 即可。请看我的回答stackoverflow.com/a/57840173/466066

标签： html themes width python-sphinx

【解决方案1】：

我会在 css 中修改它。您应该搜索文件 theme.css（它位于“sphinx_rtd_theme/static/css/theme.css”的阅读文档源中）。

复制该文件并将其放入您的 sphinx _static 目录中。在该 css 文件中，您可以进行所需的所有布局更改。（如果您从未使用过 css 文件，您可能需要阅读一些内容。）

希望这会有所帮助。

【讨论】：

【解决方案2】：

首先我必须说，在我的 sphinx quickstart 期间，我为我的 sources 和我的 build 选择了单独文件夹的选项.

这是一个 3 个步骤的过程：

1。为您的样式创建一个文档：

在哪里？

在我的conf.py 所在的同一目录中（在我的情况下为source），我为我的自定义静态文件（样式表、javascripts）创建了一个文件夹。我叫它custom。
在其中我为我的样式表创建了一个子文件夹：source/custom/css。
在这个子文件夹中，我将创建我的自定义样式：source/custom/css/my_theme.css。

2。告诉狮身人面像

现在我们必须告诉 sphinx 将此文档吐出到 build/_static/css 中，与 Read The Documents 主题中包含的样式表所在的目录相同。为此，我们将以下行添加到 conf.py:

html_static_path = ['custom']       # Directory for static files.

完成。现在，如果我们构建，我们将拥有 RTD 样式 (theme.css) 和我们自定义的 my_theme.css 在同一目录中，build/_static/css。

3。选择我们的自定义主题

现在我们要告诉 sphinx 使用我们自定义的 my_theme.css，而不是 RTD。我们这样做是在conf.py 中添加这一行：

html_style = 'css/my_theme.css'     # Choosing my custom theme.

在我们的自定义样式表中，第一行应该导入theme.css 和@import url("theme.css"); 的样式。

我们已经准备好开始覆盖样式了。

更新：还有一种更简单的方法。

1。将您的自定义设置在 `source/_static/css/my_theme.css` 中。

在您的自定义样式表中，第一行应导入 theme.css 和 @import url("theme.css"); 的样式。

这样，您不必担心会弄乱默认样式，如果您的自定义样式表不起作用，请删除并重新开始。

2。在`conf.py` 中添加以下行：

html_style = 'css/my_theme.css'

【讨论】：

感谢您指点@import。这是向 RTD 主题添加新样式表的最简单的方法
这仅适用于本地构建。如果我将我的文档发布到网站，它不会加载 .css
注意：这将不使用文件中的连字符（即 my-theme.css）。

【解决方案3】：

要使ReadTheDocs 主题使用整个屏幕宽度，您可以修改theme.css 文件，从wy-nav-content 类定义中删除max-width: 800px; 属性，如下所示：

.wy-nav-content {
    padding: 1.618em 3.236em;
    height: 100%;
    /* max-width: 800px; */
    margin: auto;
}

一些注意事项

theme.css的来源在这里：

https://github.com/rtfd/readthedocs.org/blob/master/media/css/sphinx_rtd_theme.css
它会在你的文件系统中（假设你已经运行：pip install sphinx_rtd_theme）：

lib/python2.7/site-packages/sphinx_rtd_theme/static/css/theme.css
要在 Linux/Mac 上找到 theme.css 的绝对路径，您可以在命令行上运行它（假设您已经设置了 $PYTHONPATH 环境变量）：
```
for p in `echo $PYTHONPATH | tr ":" "\n"`; do 
    find $p -type f -name 'theme.css' | grep sphinx_rtd_theme
done
```
theme.css 文件将被缩小，因此您可以使用http://unminify.com 之类的工具使其更易于阅读。

结果：

之前：

之后：

【讨论】：

【解决方案4】：

这里的解决方案有些骇人听闻。如果你想包含样式，并有一个 css 覆盖并让它在 RTD 上工作，你会想要这样的东西。

on_rtd = os.environ.get('READTHEDOCS', None) == 'True'

if not on_rtd:  # only import and set the theme if we're building docs locally
  import sphinx_rtd_theme
  html_theme = 'sphinx_rtd_theme'
  html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
  html_style = 'css/custom.css'
else:
  html_context = { 
    'css_files': [
        'https://media.readthedocs.org/css/sphinx_rtd_theme.css',
        'https://media.readthedocs.org/css/readthedocs-doc-embed.css',
        '_static/css/custom.css',
    ],  
  }

我自己对此进行了测试，它似乎可以在本地和 RTD 上运行。大量抄袭自https://blog.deimos.fr/2014/10/02/sphinxdoc-and-readthedocs-theme-tricks-2/

【讨论】：

【解决方案5】：

另一种选择是在 source/_static 中创建一个样式表，其中只包含您想要的 css，例如

.wy-nav-content {
    max-width: none;
}

或

.wy-nav-content {
    max-width: 1200px !important;
}

确保在source/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']

然后在source/_templates/layout.html 中创建一个自定义布局并执行类似的操作来包含您的样式表

{% extends "!layout.html" %}
{% block extrahead %}
    <link href="{{ pathto("_static/style.css", True) }}" rel="stylesheet" type="text/css">
{% endblock %}

假设你调用了你的样式表style.css

【讨论】：

这是我使用的解决方案。如果您使用 ReadTheDocs 进行构建，这可能是最佳选择。

【解决方案6】：

如果有人正在寻找更简单的答案... 结合来自 https://samnicholls.net/2016/06/15/how-to-sphinx-readthedocs/ 和上面的建议，我发现获取自定义窗口宽度的最简单方法如下：

在conf.py 中，添加一个添加自定义样式表的函数：
```
def setup(app):
    app.add_css_file('my_theme.css')
```
在conf.py，状态/调整：
```
html_static_path = ['_static'] 
```
如果_static 文件夹/目录不存在，则创建它。
在包含以下行的_static 文件夹中创建一个名为my_theme.css 的文件：
```
.wy-nav-content {
    max-width: 1200px !important;
}
```

【讨论】：

最简单的选择，它可以在本地和 gitlab 页面上运行。

【解决方案7】：

对于“经典”主题，解决方案简单明了：

# Add/Update "html_theme_options" like this on your conf.py
html_theme_options = {'body_max_width': '70%'}

根据您的口味调整百分比。

来自 sphinx 的参考：body_max_width（int 或 str）：文档正文的最大宽度。这可以是一个 int，它被解释为像素或一个有效的 CSS 维度字符串，例如“70em”或“50%”。如果您不想要宽度限制，请使用“无”。默认值可能取决于主题（通常为 800 像素）。

【讨论】：

【解决方案8】：

Sphinx 1.8.0b1（2018 年 9 月发布）中添加的 HTML 选项简化了流程。通过 conf.py 中的 html_css_files 选项，阅读文档文档中的 recommendation 是主题的 adding custom css。

html_css_files = [
    'custom.css',
]

把custom.css放到html静态路径文件夹中（默认是_static文件夹）。

custom.css的内容：

.wy-nav-content {
    max-width: 75% !important;
}

【讨论】：

【解决方案9】：

source\conf.py

html_theme = 'sphinx_rtd_theme'
html_style = 'css/my_theme.css'

source\_static\css\my_theme.css

@import url("theme.css");

.wy-nav-content {
    max-width: 90%;
}

这将是显示器宽度的 90%。

【讨论】：

这有帮助！我试图使用默认的雪花石膏主题，但我所做的一切都无法使显示更宽。一旦我按照这个示例将主题更改为“sphinx_rtd_theme”，结果就会更好看，并且使用了整个浏览器宽度。唷。

1。为您的样式创建一个文档：

2。告诉狮身人面像

3。选择我们的自定义主题

更新：还有一种更简单的方法。

1。将您的自定义设置在 source/_static/css/my_theme.css 中。

2。在conf.py 中添加以下行：

一些注意事项

结果：

之前：

之后：

1。将您的自定义设置在 `source/_static/css/my_theme.css` 中。

2。在`conf.py` 中添加以下行：