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

Question

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

为了做到这一点，最好的方法是什么？

Answer 1

假设条件

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

• （根路径）
  • （一些其他与本讨论无关的东西）
  • _static/
  • _templates/
  • conf.py

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

用例：Hatnotes

对于此插图，我将展示如何为“ hatnotes”创建自定义样式，该概念在MediaWiki文档中非常普遍，并且与RST中的构造 大致
相对应admonition。您可以应用此处显示的内容来创建任何自定义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添加到布局中。模板的使用在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中将股票备忘定义为“模板”的通常范例（抱歉，与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”帽子说明设置为具有默认的hatnote样式（灰色背景），并使用“ 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文件的方式添加已添加样式的hatnote
。

结束状态

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

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