在阅读文档中使用 Doxygen答案

【问题标题】：using Doxygen in read-the-docs在阅读文档中使用 Doxygen
【发布时间】：2016-07-04 01:29:45
【问题描述】：

我使用 Doxygen 和 Markdown 编写了一个中型 C++ 软件的文档。我对此非常满意，因为在更改了 xml 层后，我得到了类似的结果： http://docs.mitk.org/nightly/index.html

我想将此文档放到网上，最好使用 ReadtheDocs 之类的工具，其中文档将在“git commit”之后自动构建，并托管以供浏览。

ReadtheDocs 看起来很理想，但默认使用 Sphinx 和 reStructuredText。 Doxygen 也可以使用，但 AFAIK 只能通过呼吸。走这条路线本质上意味着如果我不想将所有 API 文档转储到一个页面中（http://librelist.com/browser//breathe/2011/8/6/fwd-guidance-for-usage-breathe-with-existing-doxygen-set-up-on-a-large-project/#cab3f36b1e4bb2294e2507acad71775f），我需要重新构建所有文档。

自相矛盾的是，Doxygen 安装在 read-the-docs 服务器中，但经过努力，我找不到跳过其 Sphinx 或 Mkdocs 的解决方法。

【问题讨论】：

标签： doxygen read-the-docs

【解决方案1】：

我已尝试以下解决方案在 Read The Docs 上使用 Doxygen，它似乎有效：

建立空sphinx项目（参考官方sphinx文档），
在 sphinx conf.py 中添加命令以构建 doxygen 文档，
使用 conf.py html_extra_path 配置指令在生成的 sphinx 文档上覆盖生成的 doxygen 文档。

我已经使用以下源代码树对此进行了测试：

.../doc/Doxyfile
       /build/html
       /sphinx/conf.py
       /sphinx/index.rst
       /sphinx/...

一些解释：

在我的设置中，doxygen 在“doc/build/html”中生成其文档，
ReadTheDocs 在找到 conf.py 文件的目录中运行其命令。

做什么：

在 conf.py 中添加以下行以生成 doxygen 文档：

 import subprocess
 subprocess.call('cd .. ; doxygen', shell=True)

将 conf.py html_extra_path 指令更新为：
```
 html_extra_path = ['../build/html']
```

在此配置中，ReadTheDocs 应正确生成和存储 Doxygen html 文档。

待办事项：

其他文档格式，例如：pdf。

【讨论】：

是的，它就像魅力一样，非常感谢。另一方面，我使用 CMake 来配置一些文件，如果它安装在 readthedocs 服务器中会很好。目前，我在 conf.py 中重新编码了这个配置，虽然让 CMake 不维护两个软件做同样的事情会很好。
上面的方法也记录在这里：breathe.readthedocs.io/en/latest/readthedocs.html
请务必查看此博文devblogs.microsoft.com/cppblog/…
很好的答案。 html_extra_path 位用于将 Doxygen 文档复制到 Sphinx 文档以使其在 Readthedocs 网站上运行是...快乐的魔法！
我总是有一个默认主页（来自未修改的 index.rst）并且看不到任何 html 页面，我是否需要在“制作 html”之前以某种方式更新 index.rst

【解决方案2】：

这个答案建立在“kzeslaf”已经给出的伟大答案之上。因此，请先按照他描述的步骤进行操作，然后再继续此处。

虽然他的回答按预期工作，但我遇到了 ReadTheDocs (RTD) 使用相当旧版本的 Doxygen（撰写本文时为 1.8.13）的问题。这给我带来了几个问题，比如报告的here。此外，如果您将 Doxygen 设置为将警告视为错误，由于版本相关的警告，您可能需要在 RTD 上覆盖此选项。

我找到了一个使用 conda 在 RTD 上升级 Doxygen 版本的简单解决方案。在项目的某处（可能在文档目录中）创建一个environment.yml 文件。内容如下：

name: RTD
channels:
  - conda-forge
  - defaults
dependencies:
  - python=3.8
  - doxygen=<VERSION>

将<VERSION> 替换为您喜欢使用且可在 conda-forge 上获得的任何版本号。使用conda search doxygen -c conda-forge 获取所有可用版本的列表，或者直接查看this site。你也可以删除=<VERSION>，conda 会自动安装最新的。

如果您还没有这样做，现在您需要创建一个RTD config file。添加以下行：

conda:
  environment: <DIRECTORY>/environment.yml

将<DIRECTORY> 替换为environment.yml 文件的实际位置（相对于您的项目根目录，例如：docs/environment.yml）。现在，如果您按照“kzelaf”答案中的所有步骤以及我提到的步骤进行操作，RTD 应该可以使用您选择的版本成功构建您的 Doxygen 文档。您可以在已创建页面的右下角查看。或者，将 subprocess.run(["doxygen", "-v"]) 添加到您的 conf.py 并检查 RTD 构建日志。

【讨论】：