在阅读文档中使用 Doxygen

Question

我使用 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 的解决方法。

Answer 1

我尝试了以下解决方案以在阅读文档时使用 Doxygen，它似乎有效：

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

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

.../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.pyhtml_extra_path指令更新为：
```
 html_extra_path = ['../build/html']
```

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

待办事项：

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

Answer 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 构建日志。

在阅读文档中使用 Doxygen

using Doxygen in read-the-docs

doxygen

read-the-docs