如何将自定义css文件添加到Sphinx？

Question

我如何添加自定义css文件？以下配置对我不起作用:

# conf.py
html_static_path = ['_static']
html_theme = 'default'
html_theme_options = {
  'cssfiles': ['_static/style.css']
}

结果:

C:\temp\test-docs\docs>make html
Running Sphinx v1.2.2
loading pickled environment... not yet created
building [html]: targets for 2 source files that are out of date
updating environment: 2 added, 0 changed, 0 removed
reading sources... [ 50%] help
reading sources... [100%] index

looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents...
Theme error:
unsupported theme option 'cssfiles' given

Answer 1

一种更简单的方法是将其添加到您的conf.py:

def setup(app):
    app.add_stylesheet('css/custom.css')  # may also be an URL

然后将文件放入_static/css/文件夹中.

Answer 2

您应该能够通过扩展默认的sphinx主题来包含自定义css.在conf.py中,您可以指定主题扩展的位置,例如.

# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']

然后在_templates中,您将创建一个名为"layout.html"的默认主题的扩展名,其中包含您的cssfiles,例如.

{# layout.html #}
{# Import the layout of the theme. #}
{% extends "!layout.html" %}

{% set css_files = css_files + ['_static/style.css'] %}

有关更多信息,请参阅sphinx有关模板的文档.

Answer 3

我正在使用狮身人面像 3.2。

我可以通过执行以下操作添加一些简单的自定义 CSS：

• conf.py在下面添加这一行html_static_path = ['_static']：

html_css_files = ['css/custom.css']

• 转到docs/_static/并添加css/custom.css

• 然后将自定义 css 添加到您的文件中$ make html

来源

Answer 4

您可以通过html_theme_options主题配置选项.查看[options]主题部分,theme.conf了解可用的内容.

但是,在全球范围内,您可以html_context在您的内容中定义conf.py以覆盖css_files(并且,就此script_files而言)的设置:

html_context = {
    'css_files': ['_static/custom.css'],
}

(作为参考,请看看Sphinx的builders.html.StandaloneHTMLBuilder.prepare_writing(),看看它是如何self.globalcontext填充的.)