Question

过去在这个主题上有几个主题，声称Sphinx根本不支持这个。我有疑虑，但要么它已经更新，或者它的文档被很好地隐藏，因为这里有一个链接在网站上说明否则： http://sphinx.pocoo.org/latest/domains.html#array:T:::subscript-operatorC

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

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

Answer 1

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

完全阅读how to use sphinx之后，您应该查看breathe：

Breathe提供了Sphinx和Doxygen文档之间的桥梁   系统

将Doxygen信息包含在一组中是一种简单的方法   Sphinx生成的文档。目的是生产autodoc   比如支持喜欢使用Sphinx但使用语言的人   除了Python。系统依赖于Doxygen的xml输出。

另外，你需要遵循Doxygen评论风格，甚至设置一个doxygen项目。但是我尝试了这一点，并且在初始设置发生后它的效果非常好。以下是our CMakeLists.txt的摘录，可能会让您了解狮身人面像与多氧化合物如何协同作用：

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"
)

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

使用doxygen path/to/config
cd进入sphinx配置所在的目录。
使用sphinx-build . path/to/output

在c ++域上：

Sphinx比自动生成文档的系统更“一点点”。我建议你看看at the examples（并考虑到sphinx网站本身是用sphinx reST代码编写的）。特别是点击许多狮身人面像生成页面上的Show Source链接。

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

.. 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 +呼吸但是使用sphinx的情况下记录您的c ++项目，您必须自己编写重组文本文件。这也意味着您从源代码中拆分文档，这可能是不可取的。

我希望稍微澄清一下。为了进一步阅读，我强烈建议您对sphinx tutorial和documentation有一个很好的阅读，直到您了解其实际行为为止。

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

1 个答案:

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

在c ++域上：