Quelqu'un a-t-il utilisé Sphinx pour documenter un projet C++ ?

Question

Sphinx est un nouvel outil de documentation pour Python. Il a l'air très bien. Ce que je me demande, c'est :

• Dans quelle mesure cela convient-il pour 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++ qui utilisent Sphinx ?
• Des conseils de la part de quelqu'un qui a utilisé Sphinx ?

Answer 1

Comme indiqué ici et ici ,

• Le support C++ natif de Sphinx est lié à la mise en évidence, au formatage et au référencement, et non à l'extraction de la documentation dans le code.
• respirez s'est développée à partir de la discussion à laquelle Chrisdew a fait référence.

[Edition insérée ci-dessous] :

J'ai testé la chaîne d'outils doxygen+breathe+sphinx sur une bibliothèque C++ de plusieurs 10k bibliothèque C++ composée de 10 modules/domaines différents. Ma conclusion résultat est le suivant :

1. pas encore totalement utilisable
2. mais continuez à regarder
3. et, surtout, pensez à consacrer un peu de temps vous-même si vous êtes actuellement à la recherche d'un projet OSS de valeur qui mérite votre temps.

Permettez-moi de développer ces points :

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

   • Balisage Latex dans le balisage doxygen (non supporté actuellement, mais devrait être facile à mettre en œuvre)
   • Quelques erreurs d'analyse (plusieurs définitions d'en-tête de fonction), qui semblent causer des erreurs dans l'analyseur sphinx, mais qui ne posent aucun problème si je les teste. l'analyseur sphinx, mais qui ne posent aucun problème si je les teste directement dans les blocs de code c++ de sphinx directement. Aucune idée de la difficulté de la correction, mais c'est un sérieux problème de fonctionnalité.
   • Des problèmes avec les identificateurs surchargés. Il semble y avoir un certain support pour adresser des fonctions avec le même nom dans des classes différentes. et/ou des espaces de noms et/ou des fichiers de sortie doxygen xml différents. Mais l'affichage ou le lien vers un constructeur spécifique parmi 10 surchargés dans une seule classe semble infaisable ATM. Dans le cas de la référence/lien, il existe même un parallèle parallèle (peut-être temporaire) au niveau de sphinx que Respire peut ou ne peut pas contourner. être en mesure de contourner.
   • Actuellement, il n'y a aucun moyen d'afficher tous les membres (ou tous les membres protégés/privés) d'une classe. d'une classe. Ceci a été introduit d'une manière ou d'une autre avec un autre correctif et doit être vraiment trivial à réparer.

   • D'une manière plus générale, sachez que l'ATM est une passerelle vers la sortie xml de Doxygen. sortie xml de Doxygen. Cela ne doit pas être compris de manière à ce qu'il produise exactement la même chose que Doxygen. exactement ce que doxygen fait, mais avec les limitations ci-dessus. Au contraire, il vous offre exactement, ni plus ni moins, les possibilités suivantes

     • déverser tout ce qui se trouve dans un domaine de sortie doxygen sur une page géante
     • montrer des fonctions, membres, structs, enums, typedefs ou classes spécifiques, qui doivent cependant être spécifiées à la main. Il existe un fork sur github qui peut ou non vouloir aborder cette question conceptuelle globale, mais aucune indication pour l'avenir.

2. A mon avis, une respiration entièrement fonctionnelle comblerait une lacune importante et et ouvrirait une voie assez cool. Donc ça vaut le coup de regarder juste à cause du gain potentiel.

3. Il semble malheureusement que la maintenance par le créateur va sévèrement diminuer à l'avenir. Donc si vous travaillez dans une entreprise et que vous pouvez convaincre votre patron que breathe lui conviendrait, ou avez un peu de temps libre et êtes et que vous recherchez un projet de grande valeur, pensez à lui donner une fourchette !

En guise de conclusion, notez également le doxylink projet contributif pour sphinx, qui pourrait fournir une solution intermédiaire : construire une structure environnante de type tutoriel qui qui fait référence à l'ancienne documentation doxygen (adaptée au style css). (je pense que l'on pourrait même injecter le même en-tête dans sphinx et par-dessus la documentation doxygen pour des raisons d'apparence). documentation doxygen pour le look'n'feels). De cette façon, votre projet conserve une affinité avec sphinx, et quand le souffle est complètement présent, vous êtes prêt à sauter dessus. Mais encore une fois : pensez à montrer un peu d'amour à breathe si cela correspond à votre agenda.

Answer 2

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

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

Utilisez le sphinx-quickstart pour construire un arbre de documentation de la pratique. Jouez avec pendant quelques jours pour apprendre comment cela fonctionne. Puis utilisez-le à nouveau pour construire la vraie chose dans les répertoires SVN.

Organisez votre documentation selon une arborescence bien conçue. Certaines sections nécessitent un "index.rst" pour cette section, d'autres non. Cela dépend du degré d'autonomie de la section.

Notre niveau supérieur index.rst ressemble à ça.

.. 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 dispose d'un module complémentaire très intéressant, appelé automodule, qui extrait la documentation des modules Python.

Mise à jour A partir de Sphinx 1.0, C et C++ sont supportés. http://sphinx.pocoo.org/

Answer 3

Jetez un coup d'œil à http://www.nabble.com/Using-doxygen-and-sphinx-together-td20989904.html pour une approche XML.