doxygen的图像路径不正确

Question

tl;博士问题:

doxygen用于查找doxygen注释中引用的图像的实际算法是什么？结果是什么被认为是未来doxygen版本不会破坏的最佳实践？

细节:

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

该Doxygen文档状态:

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提供给root的路径,但不是头文件的完整路径).

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. 此外，为了“找到”图像，文件名和路径应与图像的实际全名和路径的一部分匹配

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

/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
• /一些路径/工作/图像/一些/更多/文件夹
• 图片/一些/更多/文件夹/the-image.png
• 图像/一些/更多/文件夹

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

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