15

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

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

4

3 回答 3

28

编辑：截至 2021 年，以下答案已过时，请在 1.8 版之后使用html_css_files = []，conf.py而不是使用应用程序 API（撰写本文时的当前 Sphinx 版本为 4.1.1）。下面的add_stylesheet选项已add_css_file在 1.8 版中重命名，似乎更适用于 Sphinx 扩展开发人员。

假设

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

  • （根路径）
    • （与此讨论无关的其他一些内容）
    • _static/
    • _templates/
    • conf.py

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

用例：帽子笔记

对于这个插图，我将展示如何为“hatnotes”创建自定义样式，这个概念在 MediaWiki 文档中很流行，并且大致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上有详细记录模板的使用。在您的覆盖模板中，只需css-files使用附加的自定义 CSS 文件列表设置变量（一个数组）。

这是我的模板，它添加了 hatnotes CSS。我将此保存为_templates/layout.html.

{% extends "!layout.html" %}
{% set css_files = css_files + [ "_static/css/hatnotes.css" ] %}

这就是您需要为默认主题做的所有事情。对于 Sphinx/RTD 主题，还有一个额外的步骤，您可以在其中...</p>

第 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 文件。

结束状态

您的 doc 存储库中现在包含以下内容：

  • （根路径）
    • _static/
      • css/
        • （自定义 CSS 文件……）
    • _templates/
      • layout.html— （将您的自定义 CSS 添加到默认布局中）
    • conf.py— （具有将自定义 CSS 添加到应用程序主题的新功能）
于 2015-08-18T17:42:32.650 回答
2

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

html_css_files = [
    'css/custom.css',
]
于 2021-07-15T12:48:37.683 回答
1

添加到已接受的答案：还有其他各种方法，例如添加到 footer或添加到 extrahead。RTD 文档推荐后者。

此外，我发现该setup()功能从来都不是必需的，只要html_static_path = ['_static']您的conf.py.

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

于 2019-11-18T00:24:02.647 回答