如何从 c++ 项目生成降价文档？答案

【问题标题】：How to generate markdown documentation from c++ project?如何从 c++ 项目生成降价文档？
【发布时间】：2018-09-12 18:42:45
【问题描述】：

我正在尝试为复杂的 c++ 项目创建文档。

为此，我开始使用 Doxygen，它适合我的使用，因为我只需要注释我的项目的标题即可获得完整的 HTML 文档。该文档运行良好，风格良好。

但这是我的问题，我想在 Markdown 文件中获取此文档，以便能够将其推送到 Gitlab。

我尝试使用 moxygen 将 xml 文件转换为 md 文件。它可以工作，但不如我想要的那样正常：moxygen 自动生成的锚点不起作用。演示文稿也是一个问题，例如它将定义列表放在文件的顶部，该文件很长并且在文档中不是最有用的。

我想知道是否有一种方法可以像使用 Doxygen 一样简单地记录我的代码，但可以获得正确的降价文件（锚工作和更好的模板）。

我知道 markdown 语法很简单，但我不能自己编写整个 markdown，因为项目很大并且会经常更新，所以我需要一个通用方法来从 C++ 项目中获取 markdown 文档。

【问题讨论】：

这不是 C++ 问题。请删除标签。
其次，这基本上是一个要求文档/教程的问题。这是关于SO的题外话。请阅读help center。
为什么不将生成的 HTML 推送到 gitlab 或从生成的 LaTeX 输出或 docbook 或 ...？如果从 xml 转换为 markdown，我认为您应该联系 moxygen 的开发人员。
感谢您的回答。我不能将它作为 PDF 推送，因为我在一家公司工作，我们的文档需要直接从 gitlab 中使用，比如集成到 gitlab 的 markdown。将它作为 HTML 推送可能是一个很好的解决方案，但我还不知道如何推送它并简单地链接它，我将对此进行调查。最好的解决方案是获取适当的降价文件。
所以你需要一个 HTML 到 Markdown 的转换工具。不幸的是，它们很少见，除了少数例外，它们往往是不完整的。无论如何，工具推荐在这里是题外话。

【解决方案1】：

我前段时间遇到过类似的问题，解决起来并不容易。基本上我所做的是将文档转换为 LaTeX，然后从那里转换为 markdown。检查this 到 LaTeX->Markdown 段落（其他工具也存在）。

您可以在某种程度上使用 make/latexmke 自动化该过程，但我个人无法使该过程变得简单，有时我仍然需要介入。另请注意，您可能需要使用其他工具，例如 flex，将您的 LaTeX 文档制作成一个大的 tex 文件。一些转换程序不接受拆分tex 文件。

这并不完美，但它可能会给你另一个角度。希望对您有所帮助。

【讨论】：

感谢您的回答。我已经阅读了有关将我的 Latex 转换为 HTML 的工具，但我不知道有一种方法可以将所有 tex 文件收集到一个大文件中，所以我放弃了这个想法。但是从这个角度看它看起来更好，我下次记录时会尝试这个。我使用的解决方案是为 Doxygen 编写包含文件的文档。然后获取 XML 文档，将其转换为 Markdown，最后通过编辑生成的 Md 文件手动更正锚点问题和演示文稿。这是我找到的最好的解决方案，直到你的消息，但它仍然很长。
是的，请参阅第 3.1 节 here 获取指针。