假设

您的RTD文档集具有以下结构：

（根路径）
- （其他一些与此讨论没有密切关系的东西）
- _static/
- _templates/
- conf.py

您还使用默认主题使用sphinx-build或sphinx-autobuild在本地构建，但您部署的服务器可能会改为使用sphinx-rtd-theme。

使用案例：帽子

在这个插图中，我将展示如何为＃34; hatnotes＆＃34;创建自定义样式，这是MediaWiki文档中普遍存在的概念，它与大致对应RST中的admonition构造。您可以应用此处显示的内容来创建任何自定义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添加到布局中。模板的使用已有详细记录at sphinxdoc.org。在覆盖模板中，只需设置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主题设置了自定义样式，您实际上可以在文档中使用它们。

按照通常的方式将股票帽子定义为＆＃34;模板＆＃34;在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

在这里我们设置了＆＃34; stub＆＃34; hatnote有默认的hatnote样式，灰色背景，并使用＆＃34; stub＆＃34;图标作为内嵌图像，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/目录下的自定义CSS文件。

结束状态

您的文档存储库现在包含以下内容：

（根路径）
- _static/
  - css/
    - （自定义CSS文件...）
- _templates/
  - layout.html - （将自定义CSS添加到默认布局）
- conf.py - （使用新功能将自定义CSS添加到应用主题）

Answer 2

我不知道哪个是最“官方的”，但是如果您转到 Furo 主题（由 Sphinx 开发人员之一开发）的 "customisation" 页面，然后滚动到“自定义 CSS 文件”，它会链接指向 "injecting code" 的指南，该指南又简单地链接到 Adding Custom CSS 上的 ReadTheDocs 页面，该页面不建议运行 Python 代码（如上面的答案），而是设置一个 conf 变量，这似乎更好。

html_css_files = [
    'css/custom.css',
]

Answer 3

添加到公认的答案：为此，还有其他各种方法，例如adding to footer或adding to extrahead。后者是recommended by the RTD docs。

我还发现只要您的setup()中有html_static_path = ['_static']，就不需要使用conf.py函数。

请注意，通常应将[ "_static/css/hatnotes.css" ]的绝对路径替换为[ pathto("_static/css/hatnotes.css", True) ]，否则将不会为子目录中的RST文件加载样式表，但是对于已接受的答案来说显然没有必要。不知道为什么。

如何为reStructuredText，Sphinx，ReadTheDocs等设置自定义样式？

3 个答案:

假设