将 OpenOffice/Libreoffice 与 Doxygen 结果相结合以获取代码文档？

Question

问题

我们目前希望通过重用我们以前的 OpenOffice 结果，从手动迁移到自动化 C 代码文档。

背景

在过去的 10 年中，我们手动生成了许多 OpenOffice (*.odt) 文件，包括类似于架构的散文、“工作原理”、图形和详细的 API 描述。因此，我们为每个产品提供了一个文档（为我们的客户导出为 *.pdf）。

我们现在更改了 C 代码以使用与 Doxygen 兼容的格式和关键字，从而生成格式良好的文档（HTML+CHM，直到现在还没有 PDF）。但这当然只包括详细的 API。目标仍然是生成一个包含 prosa 和图形的单一结果文件。

考虑合并 OpenOffice 和 Doxygen 的结果，我们想知道如何以及朝哪个方向进行：

1. 转换 *.odt => *.html 并在 C-Code for Doxygen 中引用这些
2. 转换 *.odt => *.txt/png 并在 C-Code for Doxygen 中引用这些
3. 将 *.odt => *.html 作为基础并在这些文件中引用 Doxygen-HTML-Results
4. 另一种通用格式，用于合并两个结果(?)

问题

从我们的旧文档样式迁移到等效的单个文档文件（包括 Doxygen 结果）可能是最有效的方法？

Answer 1

在尝试使用 Doxygen 构建完整文档后，我最近已转换为 Sphinx + Breathe + Doxygen。我发现使用可用的文档可以抵消多种工具增加的复杂性。

Doxygen 用于您的 API 文档，保持内联有助于鼓励 API 随代码更新。

Sphinx 用于您的系统文档、架构描述等。Sphinx 是一个基于文本的重组文档系统，您需要转换现有的 ODT 文档。

Breathe 是一座桥梁，可让您将 Doxygen 文档带入 Sphinx。 Doxygen 被编译为 XML，然后 Breathe 提取 XML 并将其推送到编译后的 Sphinx 文档中。

Sphinx & Breathe 可能还有其他替代品，但我强烈推荐这样的拆分。它允许 Doxygen 做它擅长的 API，并允许你在一个你不必每天都在努力的工具中做更高级别的系统文档。