如何在Sphinx HTML输出中更改警告警告的格式或添加警告 [英] How to change format of Warning admonition or add Caution in Sphinx HTML output

问题描述

这似乎应该很简单，但是我一直在浏览文档和网络，却没有找到答案.

This seems like it should be straightforward but I've been prowling the documentation and web and haven't found the answer.

我想从Sphinx输出HTML文档.理想情况下，我希望具有三个级别的注释"类型突出显示的文本框.ReST定义了几个警告":( http://docutils.sourceforge.net/docs/ref/rst/directives.html#admonitions )，但大多数Sphinx HTML主题仅包含用于注释"和警告"的特殊格式.(我使用的是预装的主题之一，经典.)

I want to output HTML doc from Sphinx. Ideally I'd like to have three levels of "note" type highlighted text boxes. ReST defines several "admonitions": (http://docutils.sourceforge.net/docs/ref/rst/directives.html#admonitions) but most of the Sphinx HTML themes include special formatting only for Note and Warning. (I am using one of the preinstalled themes, Classic.)

我有两个问题:

1)如何自定义文档中警告"后面的颜色?

1) How can I customize the color behind Warning in my documents?

2)如何为警告添加格式样式?

2) How can I add a formatting style for Caution?

我看到所有这些最终都以< div class ="admonition warning">之类的标签结尾.... 在HTML输出中.但是我找不到该类的格式在哪里定义.它在样式表中吗?是在layout.html文件还是其他文件中?

I see that these all end up with tags like <div class="admonition warning"> ... in the HTML output. But I can't find where the formatting for that class is defined. Is it in a stylesheet? Is it in a layout.html file or some other file?

有什么可以解释主题中各种文件实际上如何交互的吗?我还没有找到好的入门书.(我也不是基于CSS的HTML的专家，所以也许这就是问题的一部分.)

Is there anything that explains how the various files in themes actually interact with each other? I haven't found a good primer. (I am no expert on css-based HTML either, so maybe that's part of the problem.)

推荐答案

好吧，我想出了更多方法，并且有一种可行的解决方法.(我仍然不确定该如何处理.)

Okay, I figured out more and have a working workaround. (I'm still not sure how I'm supposed to handle this.)

好像我的HTML代码是直接从存储在一个名为_static的目录中的级联样式表中读取的，以及输出的结果.有classic.css，它继承自basic.css.

Looks like my HTML code is reading directly from a few cascading stylesheets stored along with the output in a directory called _static. There's classic.css, which inherits from basic.css.

我不明白这些文件与Python Sphinx安装中的basic.css_t这样的文件有何关系.

I don't understand how these relate to the files named like basic.css_t that live in the Python Sphinx install.

要更改内容，我是否应该(A)尝试更改_t文件?或(B)创建一个更改后的classic.css本地副本，该副本位于我的源目录中?

To change things, should I (A) try altering the _t files? or (B) create an altered local copy of classic.css that lives in my source directory?

如果我和B一起去，还有更多问题.

If I go with B, more questions.

• 在构建时会被css_t模板中的值覆盖吗?(我想这很容易测试)
• 对样式表的修改版本使用相同的文件名是否是一种好习惯?

这是一种避免这些问题并且似乎正在做我想要的工作的解决方法，它是: https://github.com/snide/sphinx_rtd_theme/issues/117

Here's a workaround that avoids those questions and seems to be doing what I want - from this: https://github.com/snide/sphinx_rtd_theme/issues/117

• 我创建了一个覆盖样式表，其中仅包含我要更改的格式.
• 我将其存储在源目录的_static中.

• 我在conf.py中将其定义如下:

• I created an override stylesheet that includes just the formatting I want to change.
• I stored it in the _static of my source directory.

• I defined it in my conf.py as follows:

html_context = {
    'css_files': [
        '_static/theme_overrides.css', 
        ],
    }

现在，在github讨论中说这不是针对所有主题(包括问题中提到的RTD主题)的解决方案，但我认为我现在是安全的.

Now, that github discussion said that this wasn't a solution for all kinds of themes (including the RTD theme mentioned in the question) but I think I'm safe for now.

我还应该知道什么?

这篇关于如何在Sphinx HTML输出中更改警告警告的格式或添加警告的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！