搜索

Doxygen 以各种方式索引您的源代码,以便于导航和查找所需内容。然而,在某些情况下,您希望按关键字搜索而不是浏览。

HTML 浏览器默认没有跨多个页面的搜索功能,因此 Doxygen 或外部工具需要帮助实现此功能。

Doxygen 有 7 种不同的方式将搜索添加到 HTML 输出中,每种方式都有其自身的优缺点。

1. 客户端搜索

启用搜索最简单的方法是启用内置的客户端搜索引擎。该引擎仅使用 JavaScript 和 DHTML 实现,并完全在客户端浏览器上运行。因此,无需额外的工具即可使其工作。

要启用它,请在配置文件中将 SEARCHENGINE 设置为 YES,并确保将 SERVER_BASED_SEARCH 设置为 NO

此方法的另一个优点是它提供实时搜索,即搜索结果会随着您的输入而呈现和调整。

此方法也有其缺点:它仅限于搜索符号。它不提供全文搜索功能,并且不能很好地扩展到非常大的项目(然后搜索变得非常慢)。此外,搜索是从索引项目的开头进行的,因此当可用项目为 A_STRINGAA_STRINGSTRING 并在搜索框中输入 A 时,它将找到 A_STRINGAA_STRING,但当输入例如 STR 时,它只会找到 STRING 而不是 A_STRING

2. 服务器端搜索

如果您计划将 HTML 文档放置在 Web 服务器上,并且该 Web 服务器能够处理 PHP 代码,那么您也可以使用 Doxygen 内置的服务器端搜索引擎。

要启用此功能,请在配置文件中将 SEARCHENGINESERVER_BASED_SEARCH 都设置为 YES,并将 EXTERNAL_SEARCH 设置为 NO

与客户端搜索引擎相比,其优点是它提供全文搜索,并且可以很好地扩展到中等规模的项目。

缺点是它无法在本地工作(即使用“file://”URL),并且不提供实时搜索功能。

注意
将来,此选项可能会被下一个搜索选项取代。

3. 带外部索引的服务器端搜索

Doxygen 1.8.3 版本中添加了另一个基于服务器的搜索选项。通过此选项,Doxygen 生成可搜索的原始数据,并将其留给外部工具进行索引和搜索,这意味着您可以使用自己选择的索引器和搜索引擎。为了简化操作,Doxygen 附带了一个基于 Xapian 开源搜索引擎库的示例索引器 (doxyindexer) 和搜索引擎 (doxysearch.cgi)。这两个二进制文件都包含在发行版中,但默认情况下不安装;它们可以根据需要从 bin 文件夹手动复制到例如 /usr/local/bin/var/www/cgi-bin

要启用此搜索方法,请将 SEARCHENGINESERVER_BASED_SEARCHEXTERNAL_SEARCH 都设置为 YES

有关配置详细信息,请参阅 外部索引和搜索

与选项 2 相比,此方法的优点是它(可能)可以扩展到非常大的项目。还可以将多个 Doxygen 项目和外部数据组合到一个搜索索引中。与搜索引擎交互的方式使得可以从本地 HTML 页面进行搜索。此外,搜索结果具有更好的排名并显示上下文信息(如果可用)。

缺点是它需要一个可以执行 CGI 二进制文件的 Web 服务器,以及在运行 Doxygen 后额外的索引步骤。

4. Windows 编译的 HTML 帮助

如果您在 Windows 上运行 Doxygen,则可以从 Doxygen 生成的 HTML 文件制作编译的 HTML 帮助文件 (.chm)。这是一个包含所有 HTML 文件的单个文件,它还包含一个搜索索引。许多平台都有此格式的查看器,Windows 甚至原生支持它。

要启用此功能,请在配置文件中将 GENERATE_HTMLHELP 设置为 YES。要让 Doxygen 为您编译 HTML 帮助文件,您还需要使用 HHC_LOCATION 配置选项指定 HTML 编译器 (hhc.exe) 的路径,并使用 CHM_FILE 指定生成的 CHM 文件的名称。

此方法的优点是结果是一个可以轻松分发的单个文件。它还提供全文搜索。

缺点是编译 CHM 文件仅适用于 Windows,并且需要 Microsoft 的 HTML 编译器,该编译器并未得到 Microsoft 的积极支持。尽管该工具对大多数人来说运行良好,但有时会无缘无故地崩溃(多么典型)。

5. macOS 文档集

如果您在 macOS 10.5 或更高版本上运行 Doxygen,则可以从 Doxygen 生成的 HTML 文件制作“文档集”。文档集由一个具有特殊结构的目录组成,其中包含 HTML 文件以及预编译的搜索索引。文档集可以嵌入到 Xcode(Apple 提供的集成开发环境)中。

要启用文档集的创建,请在配置文件中将 GENERATE_DOCSET 设置为 YES。您可能还需要设置其他一些与文档集相关的选项。Doxygen 完成后,您将在 HTML 输出目录中找到一个 Makefile。在此 Makefile 上运行“make install”将编译并安装文档集。有关更多信息,请参阅 本文

此方法的优点是它可以很好地与 Xcode 开发环境集成,例如,允许在编辑器中单击标识符并跳转到 Doxygen 文档中的相应部分。

缺点是它只适用于 macOS 上的 Xcode。

6. Qt 压缩帮助

如果您为 Qt 应用程序框架开发或想安装它,您将获得一个名为 Qt 助手 的应用程序。这是一个用于 Qt 压缩帮助文件 (.qch) 的帮助查看器。

要启用此功能,请将 GENERATE_QHP 设置为 YES。您还需要填写其他与 Qt 帮助相关的选项,例如 QHP_NAMESPACEQHG_LOCATIONQHP_VIRTUAL_FOLDER。有关更多信息,请参阅 本文

从功能上讲,Qt 压缩帮助功能与 CHM 输出相当,额外的优点是编译 QCH 文件不受 Windows 限制。

缺点是它要求每个用户设置 Qt 4.5(或更高版本),或者将 Qt 帮助助手与文档一起分发,这由于它目前不作为单独的包提供而变得复杂。

7. Eclipse 帮助插件

如果您使用 Eclipse,您可以将 Doxygen 生成的文档作为帮助插件嵌入。它将作为帮助菜单中“帮助内容”中可以启动的帮助浏览器中的主题出现。当您首次搜索关键字时,Eclipse 将为文档生成搜索索引。

要启用帮助插件,请将 GENERATE_ECLIPSEHELP 设置为 YES,并通过 ECLIPSE_DOC_ID 为您的项目定义一个唯一标识符,即

   GENERATE_ECLIPSEHELP = YES
   ECLIPSE_DOC_ID       = com.yourcompany.yourproject

然后在 Eclipse 的 plugin 目录中创建 com.yourcompany.yourproject 目录(与 ECLIPSE_DOC_ID 的值同名),Doxygen 完成后将帮助输出目录的内容复制到 com.yourcompany.yourproject 目录。然后重新启动 Eclipse 以使其找到新插件。

Eclipse 帮助插件提供与 Qt 压缩帮助或 CHM 输出类似的功能,但它确实需要安装并运行 Eclipse。

转到 下一 部分或返回 索引