25

过去有几个关于这个主题的线程声称 Sphinx 根本不支持这个。我有我的疑虑，但要么它已经更新，要么它的文档被很好地隐藏了，因为这是网站上的一个链接，另有说明： http ://www.sphinx-doc.org/en/master/usage/重组文本/domains.html#cpp-domain

无论如何，我是 Sphinx 的新手，但我正在尝试使用它（最终）使用来自某些源 C++ 代码的一些文本来自动化文档。sphinx-apidoc -o ...到目前为止，使用该命令时我无法到达任何地方。创建了一个几乎空白的文档。我可能没有使用正确的指令，因为我不知道如何 - 支持文档无法帮助我。

任何人都可以就使其工作所需的基本步骤提供一些帮助吗？如果无法从 C++ 自动生成文档，C++ 域的用途是什么以及如何使用它们？

4

1 回答 1

43

关于自动生成 C++ 文档：

在完全阅读了如何使用 sphinx之后，您应该看看呼吸：

Breathe 在 Sphinx 和 Doxygen 文档系统之间架起了一座桥梁。

在 Sphinx 生成的一组文档中包含 Doxygen 信息是一种简单的方法。目的是为喜欢使用 Sphinx 但使用 Python 以外的其他语言的人提供类似自动文档的支持。该系统依赖于 Doxygen 的 xml 输出。

所以另外，你需要遵循Doxygen的评论风格，甚至设置一个 doxygen 项目。但我试过了，它在初始设置后运行得非常好。这是我们CMakeLists.txt的摘录，它可能会让您了解 sphinx 和 doxygen 如何协同工作：

macro(add_sphinx_target TARGET_NAME BUILDER COMMENT_STR)
    add_custom_target(${TARGET_NAME}
    COMMAND sphinx-build -b ${BUILDER} . sphinx/build/${BUILDER}
        WORKING_DIRECTORY docs
        DEPENDS doxygen
        COMMENT ${COMMENT_STR}
    )

endmacro(add_sphinx_target)

add_custom_target(doxygen
    COMMAND doxygen docs/doxygen.conf
    COMMENT "Build doxygen xml files used by sphinx/breathe."
)

add_sphinx_target(docs-html
    html
    "Build html documentation"
)

因此，在初始设置之后，基本上可以归结为：

  1. 构建 doxygen 文档doxygen path/to/config
  2. cd进入 sphinx 配置所在的目录。
  3. 建立狮身人面像文档sphinx-build . path/to/output

在 c++ 域上：

Sphinx 不仅仅是一个自动生成文档的系统。我建议您看一下示例（并考虑 sphinx 网站本身是用 sphinx reST 代码编写的）。Show Source特别是在许多 sphinx 生成的页面上单击链接。

因此，如果您无法为项目自动生成文档，则必须自己完成。基本上 sphinx 是对任何（LaTeX、HTML、...）编译器的一个 reST。所以你可以写任意文本，但优点是它有很多用于记录不同语言源代码的命令。每种语言都有自己的域（前缀或名称空间）来分隔不同语言的名称空间。因此，例如，我可以使用以下方法记录一个 python 函数：

.. py:function:: Timer.repeat([repeat=3[, number=1000000]])
    Does something nasty with timers in repetition

（来源）

我可以使用 cpp 域做同样的事情：

.. cpp:function:: bool namespaced::theclass::method(int arg1, std::string arg2)

   Describes a method with parameters and types.

（来源）

因此，如果您想在没有 doxygen+breath 而使用 sphinx 的情况下记录您的 c++ 项目，您必须自己编写重组后的文本文件。这也意味着您将文档与源代码分开，这可能是不可取的。

我希望这能把事情弄清楚一点。为了进一步阅读，我强烈建议您仔细阅读sphinx 教程和文档，直到您了解它的实际作用。

于 2012-06-28T17:16:07.253 回答