Quelqu'un a utilisé Sphinx du document à un projet C++?

Sphinx est un nouvel outil de documentation de Python. Il est très joli. Ce que je me pose est:

  • L'adéquation de ce est pour documenter un projet C++?
  • Existe-il des outils pour la conversion de la documentation existante (par exemple, doxygen) au format Sphinx?
  • Sont là en ligne/télécharger des exemples de projets C++ qui utilisent Sphinx?
  • Des conseils de quelqu'un qui a utilisé Sphinx?
  • Vous êtes-vous retrouvée à l'aide de Sphinx pour votre projet C++? Si oui, comment a été votre expérience?
InformationsquelleAutor Nick | 2009-05-07
  1. 22

    Comme mentionné 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
    • respirer s'est développé à partir de la discussion qui chrisdew référencé

    [Modifier inséré ci-dessous]:

    J'ai testé la doxygen+breathe+de sphinx de la chaîne sur un multi-10k
    La bibliothèque C++, composé de 10 modules différents/les domaines. Mon fond
    ligne est:

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

    Permettez-moi de préciser les points suivants:

    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)
      • Certaines erreurs d'analyse (plusieurs en-tête de fonction définitions), qui est apparemment la cause
        des erreurs dans le sphinx de l'analyseur, mais ne faites pas de mal si je les tester
        dans sphinx c++ blocs de code directement. Aucune idée de la difficulté de la fixation,
        mais c'est une grave fonctionnalité disjoncteur.
      • Quelques ennuis avec surchargé identifiants. Il semble y avoir un certain soutien
        pour l'adressage des fonctions avec le même nom dans différentes classes
        et/ou les espaces de noms et/ou doxygen xml des fichiers de sortie. Mais en montrant ou de liaison
        l'un spécifique de 10 constructeurs surchargés dans une classe unique semble
        impossible de l'ATM. Dans la référence de relier les cas, il n'y a même un parallèle
        (peut-être temporaire) limitation sur le sphinx niveau de respirer peut ou ne peut pas
        être capable de travailler autour de.
      • Actuellement, il n'existe aucun moyen d'afficher toutes (ou tous protected/private)
        les membres d'une classe. C'était en quelque sorte introduit avec un autre correctif
        et faut vraiment être trivial pour réparer.

      • Dans un sens plus général, être conscient qu'il ATM est un pont à Doxygen est
        xml de sortie. Qui ne doit pas être compris de telle manière qu'il
        exactement de sortie ce que doxygen n', 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
        • montrer fonctions spécifiques, les membres, les structures, énumérations, typedefs, ou des classes,
          qui, cependant, doivent être spécifiées à la main. Il est un fork sur github
          qui peut ou peut ne pas vouloir aborder ce problème conceptuel, mais
          pas de conseils pour l'avenir.

    2. À mon avis, d'une cuisine fonctionnelle respirer permettra de combler une lacune majeure et
      ouvre cool de la route. Alors, il vaut la peine de regarder juste à cause de la
      le potentiel de gain.

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

    Comme une finale pointeur, il faut aussi souligner la doxylink contrib projet pour les sphinx,
    qui peut fournir une solution intermédiaire: construire un tutoriel comme
    la structure qui fait référence à la css (style correspondance) vieux documentation 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é pour les sphinx, et quand respirer est bien là, vous êtes prêt à
    sauter sur. Mais encore une fois: pensez à montrer respirer un peu d'amour si cela correspond à votre agenda.

    InformationsquelleAutor daspostloch
  2. 11

    Tout d'abord, gardez en deux arborescences, source et build. Mettre source sous contrôle de version. Ne mettez pas build sous contrôle de version, de le reconstruire en tant que partie de l'installation.

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

    Utiliser le sphinx-quickstart de construire une documentation sur les pratiques de l'arbre. Jouer avec pendant quelques jours pour savoir comment elle fonctionne. Ensuite l'utiliser à nouveau pour construire la vraie chose en SVN répertoires.

    Organiser vos documents dans un bien planifiée de l'arbre. 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 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 $

    Remarque, nous ne "comprennent" l'API, nous venons de le référencer avec un simple lien HTML.

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

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

    • C'est super, merci. Avez-vous des exemples de la façon dont vous avez dit des classes et des méthodes de Sphinx les lire?
    • Pas du C++ commentaires. Sphinx est seulement capable de trouver autodoc commentaires dans les modules Python. Si doxygen peut tirer un bloc de commentaire d'un fichier C++, vous pouvez utiliser restructuredtext dans ce bloc de commentaire et de créer une sorte de flux de travail à partir de doxygen pour le sphinx.
    • Alors pourquoi utiliser un système comme le Sphinx s'il ne trouve pas autodoc commentaires dans le code C? Mon naïf compréhension, la capacité à extraire des observations était la principale raison les gens utilisent ces systèmes.
    • Veuillez lire le Sphinx notes de version. sphinx.pocoo.org Version 1.0 prise en charge de C et de C++.
    • merci de lire mon post à propos de code C++ d'extraction et de solutions de contournement ci-dessous
    • Vous avez écrit "Notre haut niveau de l'index.tvd ressemble à ça". Pouvez-vous être plus précis à ce que "Notre" est? Est-ce un projet open source de la source (donc le Sphinx de configuration vous expliquer) disponible en ligne à l'oeil?
    • ce projet open source...?" Pas de. "... source ... disponible en ligne". Oui. C'est dans la réponse. "ainsi, le Sphinx de configuration vous expliquer"? Pas sûr de ce qu'il y est autre que la réponse. C'est le index.rst fichier.

    InformationsquelleAutor S.Lott
  3. 4

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

    InformationsquelleAutor fadedbee