将OpenOffice/Libreoffice与Doxygen的代码文档集成在一起？

Question

问题

我们目前希望从手动转为自动的C代码文档，通过重复使用我们以前的OpenOffice结果。

背景

在过去的10年中，我们手动生成了许多OpenOffice（*.odt）文件，包括架构、'how it works'、图形和详细的API描述。因此，我们每个产品都有一个单独的文档（导出为*.pdf给我们的客户）。

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

考虑将OpenOffice和Doxygen结果合并，我们正在思考如何以及何方向进行：

1. 将*.odt => *.html并在C代码中引用这些文件以供Doxygen使用
2. 将*.odt => *.txt/png并在C代码中引用这些文件以供Doxygen使用
3. 将*.odt => *.html作为基础，并在这些文件中引用Doxygen-HTML结果
4. 是否有其他常见格式可用于合并两个结果？

问题

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

- Ralf

Answer 1

过去我花费了太多时间在尝试使用Doxygen构建完整文档上，但最近我转向使用Sphinx + Breathe + Doxygen。我发现，虽然使用多种工具会增加复杂性，但可以获得可用的文档。

Doxygen 用于 API 文档，将其与代码保持一致有助于鼓励更新 API。 Sphinx 用于系统文档、架构描述等等。Sphinx 是一个基于 restructured text 的文档系统，需要将现有的 ODT 文档转换为 Sphinx 格式。 Breathe 是一个桥接工具，使你能够将 Doxygen 文档引入 Sphinx 中。Doxygen 被编译成 XML，Breathe 提取 XML 并将其推入编译后的 Sphinx 文档中。

可能还有其他替代方案可以取代 Sphinx 和 Breathe，但我强烈推荐采用这种分离方式。它允许 Doxygen 处理 API，而且可以使用不必每天都与之斗争的工具来处理更高级别的系统文档。

- lod

---

在简要浏览 Sphinx (+Breath) 之后，我看到了 Sphinx 的优势（以及它生成的那些出色的示例）。但这意味着从面向对象转变为 Sphinx（而不是 OO => Doxygen），并且需要一个额外的工具链（Breath），这增加了复杂性和依赖性 - 这是我所不喜欢的。但是我们将对其进行分析以决定是否适合我们。感谢您提供以上问题的替代方案！Ralf - Ralf