自动更新Doxygen文档并使用户可以随时使用CMake

Question

我已经研究了多个使用CMake构建的C ++库并运行Doxygen来生成HTML文档。在这些库中的每一个库中，文档都被内置到CMake“build”目录中的“html”文件夹中，并且永远不会被任何人看到。

因为说实话，大多数人根本不喜欢阅读文档 - 更不用说搜索它了。

这导致了一些问题：

1. 是否有一个标准的位置来安装文档，一旦它建立在哪里，它使用户非常清楚文档是否可用于库？
2. 如何确保每次构建库时，文档都会自动更新并安装在此标准位置？
3. 有人使用早期版本的库时，是否有任何标准方法可以保留过去的文档版本以供参考？

Answer 1

1）根据Filesystem Hierarchy Standard

4.11.3。具体选择 如果安装了相应的子系统，则以下目录或目录的符号链接必须位于/ usr / share中： 目录说明 ... doc杂项文档（可选）

2）我想说，你可以在安装目标中添加一个命令来复制前缀/ usr / share / doc中的doxygen

在构建目录中首先使用doxygen，看起来好吧恕我直言。

3）通常使用具有包管理器的发行版，您可以创建一个doc包，因此想要“过去”doc的用户只需要获得与二进制包具有相同版本的包doc ...

注意：在Archlinux doc上附带了库，在Debian上就像你有package-doc一样，对于自制的IIRC来说也是如此

注意：您还可以配置doxygen，因此生成的错误消息可以由您的ide（例如QtCreator）解析，就像常规的gcc错误一样，这样您就可以在每次构建的错误日志中看到它们。

Answer 2

您似乎有两个非常不同的问题：

A.构建软件的开发人员甚至不知道他们正在使用的构建的doxygen部分

B.普通用户不知道有文件可用（来自doxygen或其他）

B.这不是一个真正的技术问题所以我将专注于开发人员。首先你应该让构建的doxygen部分“选择退出”，我的意思是默认启用。只需使用常规（和假的）cmake依赖项;换句话说就是骗到cmake并假装构建doxygen是构建库所必需的。在doxygen规则/命令中，使用cmake COMMENT功能，如下所示：COMMENT“doxygen building documentation in $ {DOXYOUT}”。由于通常需要一段时间，开发人员会注意到。在构建的最后使用cmake消息“提醒，你刚刚在$ {DOXYOUT}中构建了文档”

现在回到您更具体的问题：

1. 没有标准位置，但请参见上文。
2. 往上看。
3. 使用常规版本控制存储库并在每次发布时检入doxygen输出文件夹。这可以是您的发布自动化的一部分。

还可以看看https://readthedocs.org/