c++ - 使用 Sphinx-apidoc 从 C++ 代码生成文档

Question

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

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

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

Answer 1

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

阅读 how to use sphinx 后总之，你应该看看breathe :

Breathe provides a bridge between the Sphinx and Doxygen documentation systems.

It is an easy way to include Doxygen information in a set of documentation generated by Sphinx. The aim is to produce an autodoc like support for people who enjoy using Sphinx but work with languages other than Python. The system relies on the Doxygen’s xml output.

另外，您还需要关注 Doxygen评论风格，甚至设置一个 doxygen 项目。但我试过了，它在初始设置后运行得非常好。这是our 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 path/to/config
构建 doxygen 文档
2. cd进入sphinx配置所在目录。
3. 使用 sphinx-build 构建 sphinx 文档。路径/到/输出

在 c++ 域上:

Sphinx 不仅仅是一个自动生成文档的系统。我建议你看看at the examples (并认为 sphinx 网站本身是用 sphinx reST 代码编写的)。尤其是在许多 sphinx 生成的页面上单击 Show Source 链接。

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

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

( source )

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

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

   Describes a method with parameters and types.

( source )

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

我希望这能让事情变得更清楚。为了进一步阅读，我强烈建议您阅读 sphinx tutorial和 documentation直到你明白它的实际作用。