标题中的重组文本(Sphinx)图像？

Question

是否可以使用重组文本将图像放置在标题内？

就像是:

Introduction .. image:: path/to/img.png
---------------------------------------

这呈现为文本,即不解析图像语法.我没有看到任何这样的例子让我相信这可能是不可能的,但也许有人有解决办法.

我打算输出到HTML(因此可以对派生的CSS进行修改,但我更愿意改变RST源.这是因为我还打算输出到pdf(latex).

Answer 1

我无法评论@ kitsu.eb的答案,但他是对的.

我认为使用别名(即替换)可以获得更好的结果.

这里是文档的摘录,可以提供帮助:

The |biohazard| symbol must be used on containers used to
dispose of medical waste.

.. |biohazard| image:: biohazard.png

我希望这有帮助

Answer 2

这可以通过在标题中使用替换来实现：

Header Text |foo|
=================

.. |foo| image:: path/to/img.png

这里foo只是一个示例替换文本。它可以是任何东西，但不应以空格开头或结尾。

抽象替换语法如下：

+-------+-----------------------------------------------------+
| ".. " | "|" substitution text "| " directive type "::" data |
+-------+ directive block                                     |
        |                                                     |
        +-----------------------------------------------------+

当我们想插入内嵌图像，我们应该选择image的directive type。

Answer 3

使用 HTML 和 CSS，有多种方法可以将图像添加到元素中，从而产生不同的结果。我能想到的几个是：

1. 使用图像代替任何文本。在这里，我们保留文本，但将其发送到屏幕之外，因此仍然可以访问。

   h1 {
       background: url(images/image.jpg) no-repeat top center;
       display: block;
       text-indent: 100%;
       white-space: nowrap;
       overflow: hidden;
       width: XXpx;
       height: XXpx;
   }
   

2. 将图像放置在文本左侧（或者很容易放置在右侧）

   h1 {
       background: url(images/image.jpg) no-repeat top left;
       padding-left: XXpx;
   }
   

3. 在任何文本后面使用背景图像

   h1 {
       background:url(images/image.jpg) no-repeat top center;
   }
   

更具体的 CSS 选择器可用于仅针对某些标头。

您可以使用raw指令轻松地将自定义 CSS 包含在 reStructuredText 文档中，如下所示：

.. raw:: html

    <style>
        <!-- One of the CSS styles above. -->
    </style>

--stylesheet或者，您可以使用选项从命令行包含自定义 CSS 样式表rst2html.py。

为了实现与 PDF 输出相同的目的，我将窃取我的另一个答案的一部分：

显然上面的目标是 HTML 输出。但是，我没有使用过 rst2pdf，因此无法评论如何修改上述内容才能与该程序一起使用。希望其他人能对此提供答案。据我所知，rst2pdf确实支持级联样式表机制，因此（对于了解rst2pdf样式表语法的人）添加额外.. raw:: pdf角色并修改上述列表样式应该很简单。