css - 如何为 reStructuredText、Sphinx、ReadTheDocs 等设置自定义样式？

Question

我想用我自己的自定义样式扩展 Sphinx 和 ReadTheDocs 使用的主题。

我可以这样做的最佳方法是什么，以便我的更改能够坚持下去？

Answer 1

Edit: as of 2021 the following answer is outdated, please use html_css_files = [] in your conf.py instead of using the application API after version 1.8 (current Sphinx version at time of writing is 4.1.1). The add_stylesheet option below has been renamed add_css_file in version 1.8, and seems more intended for Sphinx extension developers.

假设
您的 RTD 文档集具有类似于以下结构的内容:

(根路径)

(其他一些与本次讨论无关的内容)

_static/

_templates/

conf.py

您也在使用 sphinx-build 在本地构建或 sphinx-autobuild使用默认主题，但您部署的服务器可能使用 sphinx-rtd-theme反而。
用例:帽子笔记
对于这个插图，我将展示如何为“hatnotes”创建自定义样式，这个概念在 MediaWiki 文档中很普遍，大致对应于 admonition在 RST 中构建。您可以应用此处显示的内容来创建任何自定义 CSS 并将其包含在您的文档集中。
第 1 步:创建自定义 CSS
自定义 CSS 文件应该位于 _static/ 下的某个位置。目录，因为这是构建过程和脚本会找到它的地方。我会鼓励 css/子目录，因为您可能需要添加其他自定义项，例如 JavaScript 文件。
创建您的自定义 CSS 文件并将其放在此目录中。将您的样式规范编写为您将在构建中使用的主题中可能已经存在的任何内容的叠加。也不要假设您的样式是否会覆盖主题中的现有样式，因为您无法保证何时添加与默认样式相关的样式。
这是我用于 hatnotes 的自定义 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 文件附加列表的变量(一个数组)。
这是我的模板，它添加了 hatnotes 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 中将股票帽子注释定义为"template"的通常范例(抱歉，与 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

在这里，我们设置了我们的“ stub ”帽子注释，使其具有默认的帽子注释样式、灰色背景，并使用“ stub ”图标作为内嵌图像，带有 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 添加到应用程序主题的新功能)