17

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

4

2 回答 2

15

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

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

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

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

一些解释：

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

该怎么办：

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

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

  2. 将 conf.py html_extra_path指令更新为：

     html_extra_path = ['../build/html']

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

去做：

  • 其他文档格式，例如：pdf。
于 2016-12-17T14:40:51.113 回答
0

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

虽然他的回答按预期工作，但我遇到的问题是 ReadTheDocs (RTD) 使用了相当旧的 Doxygen 版本（在撰写本文时为 1.8.13）。这给我带来了几个问题，就像这里报道的一样。此外，如果您将 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获取所有可用版本的列表或简单地查看此站点。您也可以删除=<VERSION>并且 conda 应该自动安装最新的。

现在您需要创建一个RTD 配置文件，如果您还没有这样做的话。添加以下行：

conda:
  environment: <DIRECTORY>/environment.yml

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

于 2021-07-31T12:20:35.277 回答