编辑:截至 2021 年,以下答案已过时,请使用html_css_files = []
在你的conf.py
而不是使用版本 1.8 之后的应用程序 API(撰写本文时当前的 Sphinx 版本是 4.1.1)。这add_stylesheet
下面的选项已被重命名add_css_file
在 1.8 版本中,似乎更适合 Sphinx 扩展开发人员。
假设
您的 RTD 文档集具有类似于以下结构的内容:
-
(root path)
- (其他一些与本次讨论无关的内容)
_static/
_templates/
conf.py
您还在本地使用sphinx-build
or sphinx-autobuild
使用默认主题,但您部署的服务器可能使用sphinx-rtd-theme
反而。
用例:帽子笔记
对于这个插图,我将展示如何为“hatnotes”创建自定义样式,这是 MediaWiki 文档中普遍存在的一个概念,并且对应于roughly to the admonition
在 RST 中构建。您可以应用此处显示的内容来创建任何自定义 CSS 并将其包含在您的文档集中。
第 1 步:创建自定义 CSS
自定义 CSS 文件应该位于_static/
目录,因为构建过程和脚本将在其中找到它。我会鼓励css/
子目录,因为您可能需要添加其他自定义内容,例如 JavaScript 文件。
创建您的自定义 CSS 文件并将其放入此目录中。将您的样式规范编写为您将在构建中使用的主题中可能已存在的任何内容的覆盖。另外,不要假设您的样式是否会覆盖主题中的现有样式,因为您无法保证何时会相对于默认样式添加您的样式。
这是我为帽子笔记定制的 CSS。我把这个保存在_static/css/hatnotes.css
.
.hatnote
{
border-color: #c8c8c8 ;
border-style: solid ;
border-width: 1px ;
font-size: x-small ;
font-style: italic ;
margin-left: auto ;
margin-right: auto ;
padding: 3px 2em ;
}
.hatnote-gray { background-color: #e8e8e8 ; color: #000000 ; }
.hatnote-yellow { background-color: #ffffe8 ; color: #000000 ; }
.hatnote-red { background-color: #ffe8e8 ; color: #000000 ; }
.hatnote-icon { height: 16px ; width: 16px ; }
第 2 步:向模板添加样式
对于默认主题,创建一个覆盖默认主题的模板就足够了layout.html
将您的自定义 CSS 添加到布局中。模板的使用有详细记录在 sphinxdoc.org http://sphinx-doc.org/templating.html#configuration-variables。在您的覆盖模板中,只需设置css-files
变量(一个数组),附加了自定义 CSS 文件的列表。
这是我的模板,添加了帽子注释 CSS。我将其另存为_templates/layout.html
.
{% extends "!layout.html" %}
{% set css_files = css_files + [ "_static/css/hatnotes.css" ] %}
这就是您需要为默认主题做的全部事情。对于 Sphinx/RTD 主题,还有一个额外的步骤,您...
第 3 步:将样式表添加到主题
对于 Sphinx/RTD 主题,您的模板将被忽略。您必须向您的模板添加一个函数,而不是使用模板机制conf.py
将 CSS 文件添加到应用程序主题的文件。靠近你的conf文件设置的地方html_theme
属性,添加如下内容:
def setup(app):
app.add_stylesheet( "css/hatnotes.css" )
请注意,这次没有_static/
在小路的前面;这add_stylesheet()
函数假定路径的该部分。
完成用例
现在您已经为默认主题和 Sphinx/RTD 主题设置了自定义样式,您实际上可以在文档中使用它们。
遵循 MediaWiki 中将股票帽注定义为“模板”的通常范例(抱歉,与 Sphinx 和 RTD 中的模板不同),我设置了一个includes/
存储我所有帽子笔记的目录。
以下是如何使用自定义样式信息构建帽注。这个文件是includes/hatnotes/stub-article.rst
.
.. container:: hatnote hatnote-gray
|stub| This article is a stub. Please improve the docs by expanding it.
.. |stub| image:: /images/icons/stub.png
:class: hatnote-icon
在这里,我们将“存根”帽子笔记设置为具有默认的帽笔记样式、灰色背景,并使用“存根”图标作为内嵌图像,其中hatnote-icon
应用于该图像的样式。
现在我们可以将该文件用作文档中包含的资源。
Foo Article
===========
.. include:: /includes/hatnotes/stub-article.rst
Blah blah I haven't written this article yet.
无论您使用本地默认主题还是 Sphinx/RTD 主题,帽注都将使用您通过设置添加的样式进行渲染_templates/layout.html
模板和conf.py
脚本都包含您放置在_static/
目录。
结束状态
您的文档存储库现在包含以下内容:
-
(root path)
-
_static/
-
_templates/
-
layout.html
— (将您的自定义 CSS 添加到默认布局)
-
conf.py
— (具有将自定义 CSS 添加到应用程序主题的新功能)