如何为 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

对于这个插图，我将展示如何为“hatnotes”创建自定义样式，这个概念在 MediaWiki 文档中很流行，大致 [= =25=] 在 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 添加到布局中。模板的使用有据可查 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 主题设置了自定义样式，您实际上可以在文档中使用它们了。

遵循在 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/ 目录下的自定义 CSS 文件。

结束状态

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

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

Answer 2

添加到已接受的答案：还有其他各种方法，例如adding to footer or adding to extrahead. The latter is recommended by the RTD docs.

我还发现 setup() 函数从来都不是必需的，只要你的 conf.py 中有 html_static_path = ['_static']。

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

Answer 3

我不知道哪个是最“官方的”但是如果你去 "customisation" page of the Furo theme (developed by one of the Sphinx developers) and then scroll to "Custom CSS Files" it links to a guide to "injecting code" which in turn simply links out to ReadTheDocs's page on Adding Custom CSS 不建议运行 Python 代码（如上面的答案那样）但是设置一个 conf 变量，这似乎更好。

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

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

How do I set up custom styles for reStructuredText, Sphinx, ReadTheDocs, etc.?

css

restructuredtext

python-sphinx

read-the-docs

假设