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

Question

我正在使用"阅读文档"Sphinx主题作为我的文档.在原始主题中,给出如下

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

内容或主要布局宽度设计为移动友好.但是,对于我的项目,我希望这会更广泛.我不知道HTML,因此如果任何人可以给我一些线索来增加内容(布局)宽度,我将不胜感激.

Answer 1

另一种选择是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

Answer 2

首先,我必须说,在我的sphinx 快速入门期间,我为我的源代码和构建选择了单独的文件夹选项.

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

1.为您的样式创建文档:

哪里？

1. 在我conf.py生活的同一个目录中(在我的例子中source),我为自定义静态文件(样式表,javascripts)创建了一个文件夹.我打电话给它custom.
2. 在里面我为我的样式表创建了一个子文件夹:source/custom/css.
3. 在这个子文件夹中,我将创建自定义样式: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.cssbuild/_static/css

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

现在我们要告诉sphinx使用我们的定制my_theme.css,而不是RTD.我们这样做是为了添加以下内容conf.py:

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

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

我们准备开始覆盖样式.

更新:有一种更简单的方式.

1.将您的自定义设置放在里面source/_static/css/my_theme.css.

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

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

2.在以下行中添加以下内容conf.py:

html_style = 'css/my_theme.css' 

Answer 3

万一有人还在寻找一个简单的答案......结合来自https://samnicholls.net/2016/06/15/how-to-sphinx-readthedocs/的想法 和上述建议我发现最容易获取自定义窗口宽度的方法如下:

在conf.py中添加一个添加自定义样式表的函数(只需添加以下行):

def setup(app):
    app.add_stylesheet('my_theme.css')

然后创建一个名为my_theme.css在_static,仅仅包含以下行文件夹:

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

Answer 4

Sphinx 1.8.0b1（2018 年 9 月发布）中添加的 HTML 选项简化了该过程。Read The Docs Documentation 中的建议是通过conf.py 中的选项向主题添加自定义 css。html_css_files

html_css_files = [
    'custom.css',
]

将 custom.css 放在 html 静态路径文件夹中（默认为_static文件夹）。

custom.css 的内容：

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

Answer 5

这里的解决方案有些苛刻.如果你想要包含样式,并且有一个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/

Answer 6

1. 源\conf.py

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

2. 源\_static\css\my_theme.css

@import url("theme.css");

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

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

Answer 7

我发现自己在我从事过的多个项目中重复了这种定制（当然，基于这里的精彩答案）。

所以我为此做了一个扩展，用法如下：

pip install sphinx-rtd-size

在conf.py中：

    extensions = [
        ...
        'sphinx_rtd_size',
    ]
    
    sphinx_rtd_size_width = "90%"

希望这可以简化未来用户的事情......

您可以查看pypi 页面和github 存储库。

编辑1：

澄清 - 此扩展仅与主题“sphinx_rtd_theme”相关。

Answer 8

对于“经典”主题，解决方案既简单又干净：

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

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

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