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

问题描述 投票:13回答:2

我想用自己的自定义样式扩展SphinxReadTheDocs所使用的主题。

我能做到的最好方法是什么,以便我的更改能够坚持下去?

css python-sphinx restructuredtext read-the-docs
2个回答
20
投票

假设

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

  • ((根路径)
    • (其他与本讨论无关的东西)
    • _static/
    • _templates/
    • conf.py

您还使用默认主题使用sphinx-buildsphinx-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添加到布局中。模板的使用有据可查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步:将样式表添加到主题中

对于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脚本来添加包含自定义CSS文件的样式,从而呈现出便笺放在_static/目录下。

结束状态

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

  • ((根路径)
      _static/
      • css/
        • (自定义CSS文件...)
_templates/
    • layout.html
    • (将自定义CSS添加到默认布局)
  • conf.py
  • ((具有将自定义CSS添加到应用程序主题的新功能)
  • [添加到公认的答案中:还有其他多种方法,例如adding to extraheadadding to footer。您当然也可以在<style>内使用html块,而不是样式表。

    而且我还发现setup()功能从没有必要。也许只需确保html_static_path = ['_static']中有conf.py。通常,我建议将[ "_static/css/hatnotes.css" ]替换为[ pathto("_static/css/hatnotes.css", True) ],以使其更加强大,例如如果您在子目录中有RST文件,但是css_files方法似乎没有必要,我也不知道为什么。


    0
    投票
    [添加到公认的答案中:还有其他多种方法,例如adding to extraheadadding to footer。您当然也可以在<style>内使用html块,而不是样式表。
    © www.soinside.com 2019 - 2024. All rights reserved.