Question

我使用Doxygen和Markdown编写了一个中型C ++软件的文档。我很满意它，因为在更改xml层后我最终得到了类似的东西： http://docs.mitk.org/nightly/index.html

我想在线提供这些文档，最好使用像ReadtheDocs这样的文档，文档将在＆＃34; git commit＆＃34;之后自动构建，并托管浏览。

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 doc），
在sphinx conf.py add命令中构建doxygen文档，
使用conf.py html_extra_path config指令覆盖生成的用于生成的sphinx文档的doxygen文档。

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

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

一些解释：

在我的设置中，doxygen在＆＃34; doc / build / html＆＃34;，
ReadTheDocs在找到conf.py文件的目录中运行其命令。

怎么做：

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

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

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

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

TODO：

其他文档格式，例如：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

2 个答案: