Est-ce que quelqu'un a utilisé Sphinx pour documenter un projet C++?

Question

Sphinx est un nouvel outil de documentation pour Python. Ça semble très sympa. Qu'est-ce que je me demande est:

• Comment cela convient-il de documenter un projet C++?
• Existe-t-il des outils pour convertir la documentation existante (par exemple doxygen) au format Sphinx?
• Existe-t-il des exemples en ligne/téléchargeables de projets C++ utilisant Sphinx?
• Des conseils de quiconque a déjà utilisé Sphinx?

Answer 1

D'abord, conservez deux arborescences de répertoires, source et build. Mettez source sous le contrôle de version. Ne mettez pas build sous le contrôle de version, reconstruisez-le dans le cadre de l'installation.

Ensuite, lisez http://sphinx.pocoo.org/intro.html#setting-up-the-documentation-sources.

Utilisez le sphinx-quickstart pour créer une arborescence de documentation pratique. Jouez avec cela pendant quelques jours pour apprendre comment cela fonctionne. Ensuite, utilisez-le à nouveau pour construire la chose réelle dans les répertoires SVN.

Organisez votre documentation dans un arbre bien planifié. Certaines sections ont besoin d'un "index.rst" pour cette section, d'autres non. Cela dépend de la façon dont la section est «autonome».

Notre plus haut niveau index.rst ressemble à ceci.

.. XXX documentation master file, created by sphinx-quickstart on Wed Dec 31 07:27:45 2008. 

.. include:: overview.inc 

.. _`requirements`: 

Requirements 
============ 

.. toctree:: 
    :maxdepth: 1 

    requirements/requirements 
    requirements/admin 
    requirements/forward 
    requirements/volume 

.. _`architecture`: 

Architecture 
============ 

.. toctree:: 
    :maxdepth: 1 

    architecture/architecture 
    architecture/techstack 
    architecture/webservice_tech 
    architecture/webservice_arch 
    architecture/common_features 
    architecture/linux_host_architecture 

Detailed Designs 
================ 

.. toctree:: 
    :maxdepth: 3 

    design/index 


Installation and Operations 
=========================== 

.. toctree:: 
    :maxdepth: 1 

    deployment/installation 
    deployment/operations 
    deployment/support 
    deployment/load_test_results 
    deployment/reference 
    deployment/licensing 

Programming and API's 
===================== 

.. toctree:: 
    :maxdepth: 2 

    programming/index 

**API Reference**. The `API Reference`_ is generated from the source. 

.. _`API Reference`: ../../../apidoc/xxx/index.html 

.. note:: 
    The API reference must be built with `Epydoc`_. 

    .. _`Epydoc`: http://epydoc.sourceforge.net/ 

Management 
========== 

.. toctree:: 
    :maxdepth: 2 
    :glob: 

    management/* 


Indices and tables 
================== 

* :ref:`genindex` 
* :ref:`modindex` 
* :ref:`search` 

SVN Revision 
============ 

:: 

    $Revision: 319 $ 

Notez que nous n'incluons pas l'API, nous la référençons simplement avec un lien HTML ordinaire.

Sphinx a un add-on très cool, appelé automodule, qui sélectionne les docstrings à partir de modules Python.

Mise à jour A partir de Sphinx 1.0, C et C++ sont pris en charge. http://sphinx.pocoo.org/

Answer 2

Jetez un oeil à http://www.nabble.com/Using-doxygen-and-sphinx-together-td20989904.html pour une approche XML.

Answer 3

Comme mentionné here et here,

• natif Sphinx soutien de C est liée à mettre en évidence/mise en forme/référencement, pas dans le code extraction de documentation
• breathe a développé à partir de la discussion qui a chrisdew référencé

[Modifier inséré ci-dessous]:

J'ai testé le d oxygène + respirer + chaîne d'outils sphinx sur un multi-10k Bibliothèque C++ composée de 10 modules/domaines différents.Mon bas ligne est:

1. pas encore totalement utilisable
2. mais continuer à regarder
3. et, surtout, envisager de consacrer un peu de temps vous-même si que vous recherchez actuellement un important projet OSS qui mérite votre temps.

Permettez-moi de préciser ces points:

1. J'ai eu des problèmes avec:

   • balisage en latex dans le balisage doxygen (non pris en charge actuellement, mais devrait être facile à mettre en œuvre)
   • Erreurs d'analyseur (plusieurs définitions d'en-tête de fonction), qui provoquent apparemment des erreurs dans l'analyseur de sphinx, mais ne causent aucun problème si je les teste dans les blocs de code sphinx C++ directement. Aucune idée sur la difficulté de la fixation, mais c'est un sérieux disjoncteur de fonctionnalité.
   • Problèmes avec les identifiants surchargés. Il semble y avoir un certain soutien pour l'adressage des fonctions avec le même nom dans différentes classes et/ou des espaces de noms et/ou des fichiers de sortie xx doxygen. Mais montrant ou liant à un spécifique de 10 constructeurs surchargés dans une seule classe semble ATM impossible. Dans le cas de référence/liaison, il existe même une limitation parallèle (peut-être temporaire) au niveau du sphinx qui peut respirer ou ne pas être capable de contourner le problème.
   • Actuellement, il n'existe aucun moyen d'afficher tous les membres (ou tous protégés/privés) d'une classe. Cela a été introduit avec une autre correction et doit être vraiment trivial à réparer.

   • Dans un sens plus général, sachez que l'ATM est un pont vers la sortie xml de Doxygen . Cela ne devrait pas être compris de telle manière qu'il produira exactement ce que fait doxygen, juste avec les limitations ci-dessus. Au contraire, il vous offre exactement, pas plus, pas moins, les possibilités de

     • Déverser tout dans un domaine de sortie doxygen sur une seule page géante
     • afficher des fonctions spécifiques, les membres, les structures, énumérations, typedefs, ou des classes, qui doivent cependant être spécifiées à la main. Il y a une fourchette sur github qui peut ou ne peut pas vouloir aborder ce problème conceptuel global, mais aucun indice pour le futur là.

2. À mon avis, une respiration pleinement fonctionnelle comblerait une lacune importante et ouvrir une route très cool. Donc, il vaut la peine de regarder juste à cause du gain potentiel .

3. Il semble malheureusement que la maintenance à travers le créateur va sévèrement diminuer à l'avenir.Donc, si vous travaillez dans une entreprise et pouvez convaincre votre patron qui respire lui conviendrait, ou avoir du temps libre et sont à la recherche d'un projet vraiment précieux, pensez à lui donner une fourchette!

En tant que pointeur finale, note également le projet de contrib doxylink pour sphynx, qui peut fournir une solution intermédiaire: mettre en place une structure comme tutoriel autour qui fait référence à la (css style adapté) ancienne documentation doxygen (je pense que vous pourriez même injecter le même en-tête dans sphinx et sur la documentation de doxygen pour look'n'feels). De cette façon, votre projet conserve une affinité pour le sphinx, et quand vous respirez, vous êtes prêt à sauter dessus. Mais encore une fois: envisager de montrer respirer un peu d'amour si cela correspond à votre agenda.