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

Question

我该怎么添加一个自定义的CSS文件呢？下面的conf.py代码没有效果：

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

结果：

$ 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

我正在使用 Sphinx 3.2。

我通过以下步骤成功添加了一些简单的自定义 CSS：

• 在 conf.py 文件中，找到 html_static_path = ['_static'] 这一行，然后在它下面添加这一行：

html_css_files = ['css/custom.css']

• 去 docs/_static/ 文件夹，添加一个 css/custom.css 文件。

• 在你的文件中添加自定义的 CSS，然后运行 $ make html。

来源

Answer 2

你可以通过 html_theme_options 来设置的选项是跟主题有关的。想知道有哪些可用的选项，可以查看你主题的 theme.conf 文件中的 [options] 部分。

不过，从全局来看，你可以在 conf.py 文件中定义 html_context，这样可以覆盖 css_files 的设置（还有 script_files 的设置也是一样）：

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

（如果需要参考，可以看看 Sphinx 的 builders.html.StandaloneHTMLBuilder.prepare_writing()，了解一下 如何填充 self.globalcontext。）

Answer 3

你可以通过扩展默认的sphinx主题来添加自定义的css样式。在你的conf.py文件中，你需要指定你的主题扩展的位置，比如：

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

然后在_templates文件夹里，你可以创建一个名为'layout.html'的文件，这个文件是对默认主题的扩展，里面可以包含你的css文件，比如：

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

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

想了解更多信息，可以查看sphinx的文档，特别是关于模板的部分。

Answer 4

一种更简单的方法是把这个内容加到你的 conf.py 文件里：

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

然后把这个文件放到 _static/css/ 文件夹里。