将 OpenOffice/Libreoffice 与代码文档的 Doxygen 结果结合起来？

Question

问题

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

背景

在过去的 10 年里，我们手动生成了大量 OpenOffice (*.odt) 文件，包括类似架构的程序、“它是如何工作的”、图形和详细的 API 描述。因此，我们为每个产品提供了一个文档(为我们的客户导出为 *.pdf)。

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

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

1. 转换 *.odt => *.html 并在 Doxygen 的 C 代码中引用它们
2. 转换 *.odt => *.txt/png 并在 Doxygen 的 C 代码中引用它们
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，并允许您在一个工具中执行更高级别的系统文档，而您不必每天都在争吵。