为具有特定标题的通用 sphinx 警告定义标记答案

【问题标题】：define mark up for generic sphinx admonitions with a specific title为具有特定标题的通用 sphinx 警告定义标记
【发布时间】：2012-02-06 15:52:54
【问题描述】：

我正在使用 Sphinx 为 Python 程序生成 HTML 文档。

我想使用带有特定标题的通用admonition 指令（参见http://docutils.sourceforge.net/docs/ref/rst/directives.html#generic-admonition）并以我可以定义的方式对其进行标记，例如使用note 指令生成的内容，即，盒装，但颜色不同（大多数警告没有特殊样式，参见http://sphinx.pocoo.org/rest.html?highlight=admonition）。

我该怎么做才最好？

【问题讨论】：

我不确定我是否理解。您是否希望 admonition 指令完全像 note 指令一样呈现？为什么？ “特定的狮身人面像告诫”是什么意思？
@mzjn：我编辑了问题以澄清它。
使用topic directive怎么样？
@crayzeewulf：不，我在语义上希望它是admonition；巴德的回答很好。
Okie dokie。我想要对 PDF 和 HTML 输出都有效的类似东西。主题为我完成了这项工作。

标签： markup python-sphinx restructuredtext

【解决方案1】：

如果我正确理解了您的问题，您希望将自定义 CSS 样式应用于警告。您可以使用 :class: 属性来做到这一点。

例如下面的

.. admonition:: my title goes here
   :class: myOwnStyle

   this is the admonition text

呈现为

<div class="myownstyle admonition">
  <p class="first admonition-title">my title goes here</p>
  <p class="last">this is the admonition text</p>
</div>

然后您添加自己的样式表。例如，通过 source 目录中的 _templates 目录中的自定义 layout.html：

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

然后您可以使用 myownstyle 类的选择器在样式表中使用 CSS 样式

【讨论】：

我花了几个小时才弄清楚这一点，因为我没有正确地向 Google 提出问题。您的回答很详尽，包含的有用信息比我想象的要多。
好答案。对我来说唯一缺少的是 css 文件应该是什么样子。

【解决方案2】：

这是一个 custom.css 示例，用于覆盖 myownstyle 警告的标题颜色和背景颜色。我在conf.py 中使用了app.add_stylesheet() 调用。

.rst-content .myownstyle .admonition-title {
   background: #b99976
}

.rst-content .myownstyle {
   background: #e5d3b3
}

【讨论】：

【解决方案3】：

要更方便地添加 css 文件，请将它们放在 _static 文件夹中，然后将其添加到 conf.py：

def setup(app):
    app.add_stylesheet('custom.css')

【讨论】：