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

comme indiqué ici et ici ,

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

[modifier inséré ci-dessous]:

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

1. pas encore pleinement utilisable
2. , mais de continuer à regarder
3. et, plus important encore, envisager de consacrer un certain temps vous-même si vous êtes actuellement à la recherche d'un projet OSS précieux qui mérite votre temps.

permettez-moi d'élaborer ces points:

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

   • Latex de balisage dans le doxygen balisage (non pris en charge actuellement, mais il doit être facile à mettre en œuvre)
   • quelques erreurs d'analyseur (plusieurs définitions d'en-tête de fonction), qui semblent causer les erreurs dans l'analyseur de sphinx, mais ne font aucun problème si je les teste dans sphinx C++ code bloque directement. Aucune idée de la difficulté de fixation, mais c'est une grave fonctionnalité disjoncteur.
   • quelques ennuis avec surchargé identifiants. Il semble y avoir un certain soutien pour des fonctions d'adressage avec le même nom dans des classes différentes et/ou namespaces et / ou Doxygen xml output files. Mais l'affichage ou le lien vers un des 10 constructeurs surchargés d'une seule classe semble un distributeur automatique infaisable. Dans le cas de référence/lien, il y a même un parallèle (peut-être temporaire) limitation sur le niveau de sphinx qui respire peut ou ne peut pas être capable de travailler autour de.
   • il N'y a actuellement aucun moyen pour montrer tout (ou tout protégé / privé) les membres d'une classe. Cela a été en quelque sorte introduit avec une autre correction et doit être vraiment trivial à réparer.

   • dans un sens plus général, être conscient qu'il ATM est un pont à Doxygen xml de sortie. Qui ne doit pas être compris de telle manière qu'il produit exactement ce que fait doxygen, juste avec les limitations ci-dessus. Plutôt, il vous offre exactement, pas plus, pas moins, les possibilités de

     • vider le tout dans un doxygen sortie de domaine sur un géant de la page
     • afficher les fonctions, les membres, les structures, les énums, les typographies ou les classes spécifiques, qui doit cependant être spécifié à la main. Il y a une fourchette sur github qui peuvent ou non vouloir aborder cette question conceptuelle globale, mais pas de conseils pour l'avenir.

2. à mon avis, une respiration entièrement fonctionnelle remplirait une lacune majeure et ouvrez une route assez cool. Alors, il vaut la peine de regarder juste à cause de la le potentiel de gain.

3. il semble tristement que la maintenance par le créateur va tomber sévèrement dans l'avenir. Donc, si vous travaillez dans une entreprise et peut convaincre votre patron qui respire lui conviendrait, ou avoir un peu de temps libre et sont la recherche d'un bien précieux, pensez à lui donner une fourchette!

comme final pointeur, noter également le doxylink contrib projet pour sphinx, qui peut fournir une solution intermédiaire: construire un tutoriel comme structure qui fait référence à la documentation (css-style matched) ancienne doxygen (je pense que vous pourriez même injecter le même en-tête en sphinx et sur le dessus de la la documentation doxygen pour look'n'feels). De cette façon, votre projet conserve une affinité au sphinx, et quand respirer est entièrement là, vous êtes prêt à sauter sur. Mais encore une fois: considérer montrer respirer de l'amour si cela correspond à votre programme.

tout d'abord, gardez deux répertoires, source et build . Mettez source sous contrôle de version. Ne mettez pas build sous contrôle de version, le reconstruire dans le cadre de l'installation.

deuxième, lire http://sphinx.pocoo.org/intro.html#setting-up-the-documentation-sources .

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

Organisez votre documentation dans un arbre bien planifié. Certaines sections ont besoin d'un " index.d'abord" pour cette section, certains ne le font pas. Il dépend de la façon dont "stand-alone" de la section est.

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 $

Note, Nous ne "incluons" pas L'API, nous la référencons simplement avec un lien HTML ordinaire.

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

mise à Jour Comme des Sphinx 1.0, le C et le C++ sont pris en charge. http://sphinx.pocoo.org /

regardez http://www.nabble.com/Using-doxygen-and-sphinx-together-td20989904.html pour une approche XML.