Question

tl; dr问题：

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

详细说明：

我们正在尝试制定一项政策，其中与doxygen评论相关联的任何图像都应该本地化到参考，这意味着我们将在整个源树中分布图像。显然，我们需要确保我们适当地引用图像，并且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]为以下之一：

image.png
images/image.png
./images/image.png
/full/path/to/this/images/image.png

然后我玩IMAGE_PATH变量。

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

“错误”图片已加载（other / iamges / image.png）
没有图片
没有图片
正确加载图片

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

正确加载图片
正确加载图片
正确加载图片
正确加载图片

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

“错误”图片已加载（other / iamges / image.png）
“错误”图片已加载（other / iamges / image.png）
“错误”图片已加载（other / iamges / image.png）
正确加载图片

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

推断算法属性

只有相对路径位于以IMAGE_PATH中指定的路径为根的树中时，相对路径才有效。
如果图像文件名可以分解为不同的图像，doxygen似乎会选择与参考文件“最接近”的图像。

Answer 1

第一件事...感谢您发布此信息，我开始认为我缺少明显的东西。现在我知道我们至少有两个...

我试图将图片包含在降价文件中；这也许可以解释我得到的结果略有不同。另外，我仅使用\ image命令进行了测试。最初，我只收到了一系列“未找到图片”警告，但最终我获得了一些一致的积极结果，提示：

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

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

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

要在“工作”文件夹中运行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
图片/一些/更多/文件夹

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

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

Answer 2

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

![picture](my_picture.png)

@image html my_picture.png

doxygen的图像路径不正确

2 个答案: