如何为reStructuredText，Sphinx，ReadTheDocs等设置自定义样式? [英] How do I set up custom styles for reStructuredText, Sphinx, ReadTheDocs, etc.?

问题描述

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

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

解决方案

假设

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

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

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

用例:帽子

在此示例中，我将展示如何为"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脚本以包含自定义CSS文件的方式添加帽子样式的帽子您将其放在_static/目录下.

结束状态

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

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

I want to extend the theme used by Sphinx and ReadTheDocs with my own custom styles.

What is the best way I can do this so that my changes will stick?

解决方案

Assumptions

Your RTD doc set has something like the following structure:

• (root path)
  • (some other stuff not germane to this discussion)
  • _static/
  • _templates/
  • conf.py

You're also building locally using sphinx-build or sphinx-autobuild using the default theme, but your deployed server might use the sphinx-rtd-theme instead.

Use Case: Hatnotes

For this illustration, I'm going to show how to create custom styling for "hatnotes", a concept which is prevalent in MediaWiki docs and which corresponds roughly to the admonition construct in RST. You can apply what's shown here to create any custom CSS and include it in your doc set.

Step 1: Create Custom CSS

The custom CSS file should go somewhere under the _static/ directory, as that's where the build process and scripts will find it. I would encourage a css/ subdirectory, since you might have other customizations to add, like JavaScript files.

Create your custom CSS file and put it in this directory. Write your style specifications as an overlay to whatever might already exist in the theme you'll be using in the build. Also don't assume anything about whether your style will override an existing style in the theme, as you can't guarantee when your styles will be added in relation to the default ones.

Here's my custom CSS for hatnotes. I saved this at _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 ; }

Step 2: Add Styles to Templates

For the default theme, it is sufficient to create a template that overrides the default layout.html to add your custom CSS to the layout. Use of templates is well documented at sphinxdoc.org. In your override template, simply set the css-files variable (an array) with an appended list of your custom CSS files.

Here is my template which adds the hatnotes CSS. I saved this as _templates/layout.html.

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

That's all you need to do for the default theme. For the Sphinx/RTD theme, there's an additional step, where you…

Step 3: Add Stylesheets to the Theme

For the Sphinx/RTD theme, your template will be ignored. Instead of using the template mechanism, you have to add a function to your conf.py file which adds the CSS file to the app's theme. Somewhere near where your conf file sets the html_theme attribute, add something like the following:

def setup(app):
  app.add_stylesheet( "css/hatnotes.css" )

Note that, this time, there's no _static/ at the front of the path; the add_stylesheet() function assumes that part of the path.

Finishing the Use Case

Now that you've set up your custom styles for both the default theme and the Sphinx/RTD theme, you can actually use them in your doc.

Following the usual paradigm of defining stock hatnotes as "templates" in MediaWiki (sorry, not the same as templates in Sphinx and RTD), I set up an includes/ directory where all my hatnotes would be stored.

Here's how to construct a hatnote with the custom style information. This file is 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

Here we set up our "stub" hatnote to have the default hatnote styling, the gray background, and use a "stub" icon as the inline image, with the hatnote-icon style applied to that image.

Now we can use the file as an included resource in a document.

Foo Article
===========

.. include:: /includes/hatnotes/stub-article.rst

Blah blah I haven't written this article yet.

Whether you're using the local default theme or the Sphinx/RTD theme, the hatnote will be rendered with the styles you added by setting up the _templates/layout.html template and the conf.py script to both include the custom CSS file you put under the _static/ directory.

End State

Your doc repository now has this stuff in it:

• (root path)
  • _static/
    • css/
      • (custom CSS files…)
  • _templates/
    • layout.html — (adds your custom CSS to the default layout)
  • conf.py — (with new function to add custom CSS to app's theme)

这篇关于如何为reStructuredText，Sphinx，ReadTheDocs等设置自定义样式?的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！