tutorial software español documentar documentacion como python documentation python-sphinx

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



sphinx software (3)

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 de C ++?
  • ¿Hay alguna herramienta para convertir la documentación existente (por ejemplo, doxygen) al formato Sphinx?
  • ¿Hay ejemplos en línea / descargables de proyectos en C ++ que usan Sphinx?
  • ¿Alguna sugerencia de alguien que haya usado Sphinx?

Como se menciona here y here ,

  • La compatibilidad con C ++ nativa de Sphinx está relacionada con resaltar / formatear / referenciar, no con extracción de documentación en código
  • breathe ha desarrollado fuera de la discusión que Chrisris se refirió

[Editar insertado a continuación]:

Probé la cadena de herramientas doxygen + breathe + sphinx en una biblioteca multi-10k C ++ que consta de 10 módulos / dominios diferentes. Mi conclusión es:

  1. aún no completamente utilizable
  2. pero sigue mirando
  3. y, lo más importante, considere dedicar algo de tiempo usted mismo si actualmente está buscando un valioso proyecto de OSS que merezca su tiempo.

Permítanme elaborar estos puntos:

  1. Tuve problemas con:

    • Etiquetado de látex dentro del marcado de doxygen (no compatible 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 solucionarlo, pero este es un factor de interrupción de la funcionalidad serio.
    • Algunos problemas con los identificadores sobrecargados. Parece haber 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 / enlace, incluso hay una limitación paralela (quizás temporal) en el nivel de la esfinge que puede o no ser capaz de evitar.
    • Actualmente no hay forma de mostrar todos (o todos los miembros protegidos / privados) de una clase. Esto de alguna manera se introdujo con otra solució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 produzca exactamente lo que doxygen hace, solo con las limitaciones anteriores. Más bien, le ofrece exactamente, no más, no menos, las posibilidades de

      • volcar todo en un dominio de salida doxygen en una página gigante
      • muestra funciones específicas, miembros, estructuras, enumeraciones, tipos de archivos o clases, que sin embargo deben especificarse a mano. Hay un fork 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, una respiración completamente funcional llenaría una brecha importante y abriría un camino bastante bueno. Por lo tanto, vale la pena mirar solo por la ganancia potencial.

  3. Por desgracia, parece que el mantenimiento a través del creador disminuirá severamente en el futuro. Entonces, si trabajas en una empresa y puedes convencer a tu jefe de que lo respirarás, o si tienes algo de tiempo libre y estás buscando un proyecto realmente valioso, ¡considera darle un tenedor!

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

Primero, mantenga dos árboles de directorios, source y build . Ponga la source bajo control de versión. No coloque la build bajo el control de la versión, recupérela como parte de la instalación.

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

Use sphinx-quickstart para construir 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 primer índice index.rst parece a esto.

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

Tenga en cuenta que no "incluimos" la API, solo la referenciamos con un enlace HTML ordinario.

Sphinx tiene un add-on 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. Sphinx