doxygen 的图像路径不正确

Question

tl;博士问题：

doxygen 用于查找 doxygen cmets 中引用的图像的实际算法是什么？那么推论，什么被认为是在未来的 doxygen 版本中不会破坏的最佳实践？

详情：

我们正在尝试制定一项政策，其中与 doxygen cmets 关联的任何图像都应本地化到参考，这意味着我们将在整个源树中分布图像。显然，我们需要确保正确引用图像，并且 doxygen 可以找到它们以生成正确的文档。

doxygen documentation 声明：

doxygen 将在 IMAGE_PATH 标记后指定的路径（或文件）中查找文件

但是，在我的修修补补中，我得出的结论是，这似乎并不完全正确。以下是一些实验结果：

================================================ =

实验

文件系统配置：

/full/
   path/
      doxygen.cfg
      to/
         this/
            header.h
            images/
               image.png
      other/
         images/
            image.png

doxygen 配置文件位于树的“根”中（即/full/path/），并且从同一文件夹执行 doxygen。header.h 引用位于同一树中的 images/image.png (/full/path/to/this)。在树的其他地方有一个同名的图像文件。 header.h 有一行：

@file html [filename]

[filename] 是以下之一的参考：

1. image.png
2. images/image.png
3. ./images/image.png
4. /full/path/to/this/images/image.png

然后我使用 IMAGE_PATH 变量。

案例 1：IMAGE_PATH =（即未定义路径）。

1. 加载“错误”图像 (other/iamges/image.png)
2. 没有图片
3. 没有图片
4. 已加载正确的图像

案例 2：IMAGE_PATH = /full/path（提供给根目录的路径，但不是头文件的完整路径）。

1. 已加载正确的图像
2. 已加载正确的图像
3. 已加载正确的图像
4. 已加载正确的图像

案例 3：IMAGE_PATH = /full/path/other（提供给根目录的路径不包含头文件）。

1. 加载“错误”图像 (other/iamges/image.png)
2. 加载“错误”图像 (other/iamges/image.png)
3. 加载了“错误”图像 (other/iamges/image.png)
4. 已加载正确的图像

================================================ =

推断的算法属性

1. 仅当相对路径位于以IMAGE_PATH 中指定的路径为根的树中时，相对路径才有效。
2. 在图像文件名可以解析为不同图像的情况下，doxygen 似乎会选择与参考“最接近”的图像。

Answer 1

首先...感谢您发布此信息，我开始认为我遗漏了一些明显的东西。现在我知道我们至少有两个人......

我试图在 Markdown 文件中包含图片；这可以解释我得到的略有不同的结果。另外，我仅使用 \image 命令进行了测试。起初我只收到一长串“找不到图像”的警告，但最终我得到了一些一致的积极结果，表明：

1. 仅当 IMAGE_PATH 设置直接指向图像所在的文件夹（无父文件夹）时才能找到图像。手册通过建议 IMAGE_PATH 可能包含路径集合或文件稍微暗示了这一点
2. IMAGE_PATH 可以表示为相对于 DOXYGEN 运行位置的完整路径或
3. 此外，为了“找到”图像，文件名和路径应该与图像的实际全名和路径的一部分匹配

例如，给定一个降价页面和以下文件夹中的图像：

/some-path/work/my-page.md
/some-path/work/images/some/more/folders/the-image.png

为了在“work”文件夹中运行 DOXYGEN 时复制页面，IMAGE_PATH 应设置为以下之一：

• /some-path/work/images/some/more/folders/the-image.png
• /some-path/work/images/some/more/folders
• images/some/more/folders/the-image.png
• 图像/一些/更多/文件夹

在所有的情况下，图片可以在markdown页面中成功引用为“the-image.png”或“folders/the-image.png”、“more/folders/the -image.png" 等。标准是实际文件路径和名称的引用匹配部分（虽然人们可能期望图像引用与其出现的降价文件相关 - 这似乎是错误的）。

我再说一遍，这些测试是使用降价文件进行的，在这种情况下，机制可能与适用于源文件中引用的图像的机制不同。

Answer 2

在 html 文档中，图像被替换为损坏的图像图标。 经过两天的反复试验，我发现原因是在设置的文本方向（Project->OUTPUT_TEXT_DIRECTION），应该是None，而不是LTR。文档以两种方式进行：

![picture](my_picture.png)

@image html my_picture.png