<style>
内使用html
块,而不是样式表。我想用自己的自定义样式扩展Sphinx和ReadTheDocs所使用的主题。
我能做到的最好方法是什么,以便我的更改能够坚持下去?
您的RTD文档集具有以下结构:
_static/
_templates/
conf.py
您还使用默认主题使用sphinx-build
或sphinx-autobuild
在本地构建,但是部署的服务器可能改用sphinx-rtd-theme
。
对于这个例子,我将展示如何为“ hatnotes”创建自定义样式,该概念在MediaWiki文档中很普遍,并且与RST中的admonition
结构相对应。您可以应用此处显示的内容来创建任何自定义CSS并将其包含在文档集中。步骤1:创建自定义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步:将样式表添加到主题中
conf.py
文件中添加一个函数,以将CSS文件添加到应用程序的主题中。在conf文件设置html_theme
属性的位置附近,添加如下内容:def setup(app):
app.add_stylesheet( "css/hatnotes.css" )
请注意,这次,路径的前面没有_static/
;add_stylesheet()
函数假定路径的那部分。
完成用例
[在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
脚本来添加包含自定义CSS文件的样式,从而呈现出便笺放在_static/
目录下。结束状态
_static/
css/
_templates/
layout.html
— conf.py
— 而且我还发现setup()
功能从没有必要。也许只需确保html_static_path = ['_static']
中有conf.py
。通常,我建议将[ "_static/css/hatnotes.css" ]
替换为[ pathto("_static/css/hatnotes.css", True) ]
,以使其更加强大,例如如果您在子目录中有RST文件,但是css_files
方法似乎没有必要,我也不知道为什么。