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

Question

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

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

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

Answer 1

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

在阅读了如何使用狮身人面像之后,你应该看看呼吸:

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

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

另外,你需要遵循Doxygen评论风格,甚至设置一个doxygen项目.但是我尝试了这一点,并且在初始设置发生后它的效果非常好.以下是我们CMakeLists.txt的摘录,它可以让您了解狮身人面像和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文档 sphinx-build . path/to/output

在c ++域上:

Sphinx比自动生成文档的系统更"一点点".我建议你看看这些例子(并考虑到sphinx网站本身是用sphinx reST代码编写的).特别是点击Show Source许多狮身人面像生成页面上的链接.

因此,如果您无法自动为项目生成文档,则必须自己完成.基本上,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 +呼吸但是使用sphinx的情况下记录您的c ++项目,您必须自己编写重组文本文件.这也意味着您从源代码中拆分文档,这可能是不可取的.

我希望稍微澄清一下.为了进一步阅读,我强烈建议您阅读sphinx教程和文档,直到您了解它的实际功能.