¿Alguien ha usado Sphinx para documentar un proyecto de C++?

Question

Sphinx es una nueva herramienta de documentación para Python. Se ve muy bien. Lo que me pregunto es:

• ¿Qué tan adecuado es esto para documentar un proyecto en C++?
• ¿Hay alguna herramienta para convertir la documentación existente (por ejemplo, doxygen) a formato Sphinx?
• ¿Hay ejemplos en línea/descargables de proyectos en C++ que usan Sphinx?
• ¿Algún consejo de alguien que haya usado Sphinx?

Answer 1

En primer lugar, mantener dos árboles de directorios, source y build. Ponga source bajo control de versión. No ponga build bajo control de versión, recupérelo como parte de la instalación.

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

Utilice sphinx-quickstart para crear un árbol de documentación de práctica. Juega con esto durante unos días para aprender cómo funciona. Luego, úsela de nuevo para construir la cosa real en directorios SVN.

Organice su documentación en un árbol bien planificado. Algunas secciones necesitan un "index.rst" para esa sección, otras no. Depende de qué tan "independiente" sea la sección.

Nuestro nivel superior index.rst se parece así.

.. 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 $ 

Nota: no "incluimos" la API, solo la referenciamos con un enlace HTML ordinario.

Sphinx tiene un complemento muy genial, llamado automodule, que selecciona las cadenas de documentos de los módulos de Python.

Actualización A partir de Sphinx 1.0, C y C++ son compatibles. http://sphinx.pocoo.org/

Answer 2

Echa un vistazo a http://www.nabble.com/Using-doxygen-and-sphinx-together-td20989904.html para un enfoque XML.

Answer 3

Como se ha mencionado here y here,

• Sphinx nativa soporte para C++ está relacionada con relieve/formato/referencias, no en el código de extracción de documentación
• breathe ha desarrollado a partir de la discusión que chrisdew referencia

[Editar insertado a continuación]:

He probado la d oxygen + breathe + sphinx toolchain en un multi-10k biblioteca C++ que consta de 10 módulos/dominios diferentes.Mi parte inferior línea es:

1. aún no plenamente utilizable
2. pero seguir viendo
3. y, sobre todo, la posibilidad de dedicar algún tiempo a sí mismo si actualmente está buscando un proyecto valioso OSS que merece su hora.

Permítanme desarrollar estos puntos:

1. he tenido problemas con:

   • marcado látex dentro del margen de beneficio doxygen (no se admite actualmente, pero debería ser fácil de implementar)
   • Algunos errores de analizador (varias definiciones de encabezado de función), que aparentemente causan errores en el analizador de sphinx, pero no causan problemas si los pruebo en bloques de código sphinx C++ directamente. No tengo idea de la dificultad de la fijación, , pero este es un factor de interrupción de la funcionalidad grave.
   • Algunos problemas con los identificadores sobrecargados. Parece que hay algo de soporte para direccionar funciones con el mismo nombre en diferentes clases y/o espacios de nombres y/o archivos de salida doxgen xml. Pero mostrar o vincular a un específico de 10 constructores sobrecargados en una sola clase parece ATM no factible. En el caso de referencia/vinculación, incluso existe una limitación paralela (quizás temporal) en el nivel de esfinge que respira o no puede funcionar.
   • Actualmente no hay forma de mostrar todos (o todos los protegidos/privados) miembros de una clase. Esto de alguna manera se introdujo con otra corrección y debe ser realmente trivial para reparar.

   • En un sentido más general, tenga en cuenta que ATM es un puente hacia la salida xml de Doxygen. Eso no debe entenderse de tal manera que dará exactamente lo que hace doxygen, solo con las limitaciones anteriores. Más bien, se le ofrece exactamente, no más, no menos, las posibilidades a

     • volcar todo en un solo dominio de salida doxygen en una página gigante
     • muestran específicas funciones, miembros, estructuras, enumeraciones, typedefs, o clases, que, sin embargo, deben especificarse a mano. Hay una bifurcación en github que puede o no querer abordar este problema conceptual general, pero no hay pistas para el futuro allí.

2. En mi opinión, un completo y funcional respirar llenaría un hueco importante y abren una carretera bastante fresco. Vale la pena ver solo por la ganancia potencial .

3. Por desgracia, parece que el mantenimiento a través del creador se reducirá severamente en el futuro.Por lo tanto, si trabaja en una empresa y puede convencer al de que su jefe que respira le vendría bien, o tiene algo de tiempo libre y está buscando un proyecto realmente valioso, ¡considere darle un tenedor!

Como un puntero final, también tenga en cuenta el proyecto doxylink contrib de esfinge, que puede ofrecer una solución intermedia: construir una estructura circundante tutorial similar a la que hace referencia a la (de estilo CSS emparejado) Documentación Doxygen edad (creo que incluso podría inyectar el mismo encabezado en sphinx y en la parte superior de la documentación de doxygen para look'n'feels). De esta forma, su proyecto mantiene una afinidad con la esfinge, y cuando respire completamente, está preparado para saltar al . Pero de nuevo: considere mostrar algo de amor si se ajusta a su agenda.