修改 Sphinx 主题“阅读文档”的内容宽度

Posted

技术标签:

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

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

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

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

【问题讨论】：

2019 年，只需通过 html_css_files 选项添加所需的 css 即可。请看我的回答***.com/a/57840173/466066 【参考方案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”，结果就会更好看，并且使用了整个浏览器宽度。唷。

以上是关于修改 Sphinx 主题“阅读文档”的内容宽度的主要内容，如果未能解决你的问题，请参考以下文章

搭建 WordPress 个人博客（阅读文档）

typora 两边太宽，设置宽度

sphinx - 如何更改文档样式表

自定义 sphinxdoc 主题

制作PDF时如何替换Sphinx封面

sphinx 编写文档使用记录