Utilisation de Sphinx apidoc pour générer de la documentation à partir du code C++

Sur l'auto-génération de documentation de C++:

Après avoir lu sur comment utiliser sphinx tout, vous devriez regarder dans respirer:

Breathe fournit un pont entre la documentation Sphinx et Doxygen système.

C'est un moyen facile d'inclure Doxygen informations dans un ensemble de documentation générée par Sphinx. L'objectif est de produire un autodoc comme le soutien pour les personnes qui aiment utiliser Sphinx mais travailler avec les langues d'autres que Python. Le système s'appuie sur la sortie xml du Doxygen.

donc en plus, vous devrez suivre Doxygen commentant le style et même la mise en place d'un projet doxygen. Mais j'ai essayé et ça marche vraiment bien après l'installation initiale a eu lieu. Voici un extrait de notre CMakeLists.txt ce qui pourrait vous donner une idée de la façon dont sphinx et doxygen travaillent ensemble:

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

donc après la configuration initiale, essentiellement, il se résume à:

1. construire la documentation doxygen avec doxygen path/to/config
2. cd dans le répertoire où se trouve la configuration sphinx.
3. construire sphinx documentation sphinx-build . path/to/output

sur le domaine c++:

Sphinx est un" petit peu " plus qu'un système pour générer automatiquement de la documentation. Je vous suggère d'avoir un coup d'oeil exemples (et considérer que le site sphinx lui-même est écrit en code de repos sphinx). En particulier, cliquez sur le Show Source lien sur de nombreuses pages générées par sphinx.

donc si vous ne pouvez pas générer de la documentation automatiquement pour un projet, vous devez le faire vous-même. Essentiellement sphinx est un repos pour n'importe quel compilateur (LaTeX, HTML,...). Donc, vous pouvez écrire du texte arbitaire, mais l'avantage est qu'il a beaucoup de commandes pour documenter le code source de différentes langues. Chaque langue obtient son propre domaine (préfixe ou namespace) pour séparer les namespaces de les différentes langues. Ainsi, par exemple, je peux documenter une fonction python en utilisant:

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

( source)

je peux faire la même chose à l'aide de la rpc de domaine:

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

   Describes a method with parameters and types.

( source)

donc si vous voulez documenter votre projet c++ sans doxygen+breathe mais avec sphinx, vous devrez écrire vous-même les fichiers texte restructurés. Cela signifie également que vous divisez la documentation de votre code source, qui peut être indésirable.

j'espère que efface un peu les choses. Pour plus de lecture I fortement suggèrent que vous avez une bonne lecture sur le tutorial sphinx et documentation jusqu'à ce que vous compreniez ce qu'il fait réellement.