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

Question

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

我能做到这一点的最佳方式是什么,以便我的改变能够坚持下去？

Answer 1

假设

您的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文件的附加列表设置变量(数组).

这是我的模板,它添加了帽子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添加到应用程序的主题)