定义带有特定标题的通用狮身人面像警告的标记

Question

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

我想使用具有特定标题的

generic admonition

指令，并以我可以定义的方式对其进行标记，例如使用

note

指令生成的内容，即装箱，但具有不同的颜色（大多数警告没有特殊风格）。

我该如何最好地解决这个问题？

Answer 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 样式

Answer 2

要更轻松地添加 css 文件，请将它们放在

_static

文件夹中，然后将其添加到

conf.py

:

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

Answer 3

这是一个示例 custom.css，用于覆盖

myownstyle

警告的标题颜色和背景颜色。 我在

app.add_stylesheet()

中使用了

conf.py

调用。

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

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

Answer 4

以下是我对此的看法：

1. 添加静态文件需要满足的要求：

   • 在

     conf.py

     ：

     添加以下内容：

     • html_static_path = ['_static']

     • 添加css文件路径：

       • 要添加到列表的 css 文件的名称

         html_css_files

         :

          html_css_files = [
             'css/some_file.css',
             'css/custom.css',  # Create a Custom CSS file and add
          ]
         

     • 注意：作为推论，CSS 文件的位置将是（路径）：

       _static/css/custom.css

       （或替代 css选择的任何其他文件夹名称）

2. 向admonition（或directive）添加一个类 - 详细信息此处

   如@Bud here 上面所详述（为了简洁而添加）：

      .. admonition:: A Title
         :class: clsMyTitle
   

3. 创建文件

   custom.css

   （如果尚未完成）并添加以下内容：

    .admonition.clsmytitle {    /*Lowercase class name*/
        background-color: #e8cfe7;
        /* options as needed */
     }
   

4. 临别注：从今天（2024）开始，我们可以完成上述所有操作，而不必求助于创建我们自己的（自定义）

   layout.html

5. 在Sphinx v 7.2.6、Python 3.9

   中测试

6. 对于@Mad Physicist，人们总是可以尝试一下：如何将类名添加到警告中......。 （实际上，我正在寻找在我的页面中创建浮动框的方向，并且由于意外（或由于Google著名的算法的怜悯）碰巧降落在这里。