如何将自定义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

更简单的方法是将其添加到您的

conf.py

：

def setup(app):
    app.add_css_file('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”的默认主题的扩展，其中将包含您的 css 文件，例如。

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

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

有关更多信息，请参阅 sphinx 的有关 templatating 的文档。

Answer 3

您可以通过

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

。）

Answer 4

我使用的是Sphinx 3.2。

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

将此行添加到
• conf.py

   正下方的 

  html_static_path = ['_static']

   中：

html_css_files = ['css/custom.css']

• 转到

  docs/_static/

   并添加 

  css/custom.css

• 将自定义CSS添加到您的文件中，然后

  $ make html

来源