自动更新 Doxygen 文档并使用户可以随时使用 CMake
Automatically updating Doxygen documentation and making it readily available to users with CMake
我曾使用 CMake 和 运行 Doxygen 构建的多个 C++ 库来生成 HTML 文档。在这些库中的每一个中，文档都内置在 CMake "build" 目录中的 "html" 文件夹中，并且永远不会被任何人查看。
因为老实说，大多数人根本不喜欢阅读文档 - 更不用说搜索了。
这引出了几个问题：
是否有一个标准的位置来安装文档，一旦它被构建，用户可以非常清楚地知道文档可用于库？
我如何确保每次构建我的库时，文档都会自动更新并安装在这个标准位置？
是否有任何标准方法可以保留过去版本的文档以供参考，以防有人使用该库的早期版本？
1) 根据Filesystem Hierarchy Standard
4.11.3. Specific Options
The following directories, or symbolic links to directories, must be in /usr/share, if the corresponding subsystem is installed:
Directory Description
...
doc Miscellaneous documentation (optional)
2) 我会说，你可以在安装目标中添加一个命令来复制 prefix/usr/share/doc[=27= 中的 doxygen ]
首先在构建目录中添加 doxygen，恕我直言似乎没问题。
3) 通常，对于具有包管理器的发行版，您可以创建一个文档包，因此想要 "past" 文档的用户只需要获取与二进制包具有相同版本的包文档...
注意：在 Archlinux 上，文档随库一起提供，在 Debian 上，就像你有 package-doc，自制软件 IIRC 也是如此
注意：您还可以配置 doxygen，这样生成的错误消息就可以像常规 gcc 错误一样被 ide（例如 QtCreator）解析，这样您就可以在每次构建时在错误日志中看到它们。
您似乎有两个截然不同的问题：
一个。构建软件的开发人员甚至不知道他们正在使用的构建的 doxygen 部分
乙。普通用户也不知道有可用的文档（来自 doxygen 或其他）
乙。这不是一个真正的技术问题，所以我将专注于开发人员。首先，您应该将 doxygen 作为构建的一部分 "opt-out"，我的意思是默认启用。只需为此使用常规（和伪造的）cmake 依赖项；换句话说，对 cmake 撒谎并假装构建库需要构建 doxygen。在 doxygen rule/command 中，使用 cmake COMMENT 功能，像这样：COMMENT "doxygen building documention in ${DOXYOUT}"。由于通常需要一段时间，开发人员会注意到。在构建的最后使用 cmake 消息 "Reminder, you just built documentation in ${DOXYOUT}"
现在回到您更具体的问题：
- 没有标准位置，但请参阅上面的内容。
- 见上文。
- 使用常规版本控制存储库，并在每次发布时检查 doxygen 输出文件夹。这可以成为您发布自动化的一部分。
我曾使用 CMake 和 运行 Doxygen 构建的多个 C++ 库来生成 HTML 文档。在这些库中的每一个中，文档都内置在 CMake "build" 目录中的 "html" 文件夹中，并且永远不会被任何人查看。
因为老实说，大多数人根本不喜欢阅读文档 - 更不用说搜索了。
这引出了几个问题：
是否有一个标准的位置来安装文档，一旦它被构建，用户可以非常清楚地知道文档可用于库？
我如何确保每次构建我的库时，文档都会自动更新并安装在这个标准位置？
是否有任何标准方法可以保留过去版本的文档以供参考，以防有人使用该库的早期版本？
1) 根据Filesystem Hierarchy Standard
4.11.3. Specific Options
The following directories, or symbolic links to directories, must be in /usr/share, if the corresponding subsystem is installed:
Directory Description
...
doc Miscellaneous documentation (optional)
2) 我会说，你可以在安装目标中添加一个命令来复制 prefix/usr/share/doc[=27= 中的 doxygen ]
首先在构建目录中添加 doxygen，恕我直言似乎没问题。
3) 通常，对于具有包管理器的发行版，您可以创建一个文档包，因此想要 "past" 文档的用户只需要获取与二进制包具有相同版本的包文档...
注意：在 Archlinux 上，文档随库一起提供，在 Debian 上，就像你有 package-doc，自制软件 IIRC 也是如此
注意：您还可以配置 doxygen，这样生成的错误消息就可以像常规 gcc 错误一样被 ide（例如 QtCreator）解析，这样您就可以在每次构建时在错误日志中看到它们。
您似乎有两个截然不同的问题：
一个。构建软件的开发人员甚至不知道他们正在使用的构建的 doxygen 部分
乙。普通用户也不知道有可用的文档（来自 doxygen 或其他）
乙。这不是一个真正的技术问题，所以我将专注于开发人员。首先，您应该将 doxygen 作为构建的一部分 "opt-out"，我的意思是默认启用。只需为此使用常规（和伪造的）cmake 依赖项；换句话说，对 cmake 撒谎并假装构建库需要构建 doxygen。在 doxygen rule/command 中，使用 cmake COMMENT 功能，像这样：COMMENT "doxygen building documention in ${DOXYOUT}"。由于通常需要一段时间，开发人员会注意到。在构建的最后使用 cmake 消息 "Reminder, you just built documentation in ${DOXYOUT}"
现在回到您更具体的问题：
- 没有标准位置，但请参阅上面的内容。
- 见上文。
- 使用常规版本控制存储库，并在每次发布时检查 doxygen 输出文件夹。这可以成为您发布自动化的一部分。