c - 将 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，并允许你在一个你不必每天都在努力的工具中做更高级别的系统文档。