c++ - libreria - ¿Cuáles son las principales diferencias de Sphinx y Doxygen?

opencv python download (1)

Quiero preparar una documentación para una colección de proyectos, módulos y bibliotecas en el campo de la visión por computadora (principalmente escrita en c ++). Con este fin eché un vistazo a la documentación de OpenCV y, como sabrá, la documentación de OpenCV 2.4.x está basada en Sphinx y fue la solución exacta que estaba buscando. las buenas características de Sphinx son:

Estructura jerárquica de los módulos en el punto de vista semántico. Por ejemplo, Kalman Filter es un elemento secundario del módulo Motion Analysis y Object Tracking
Puedes agregar imágenes y también fórmulas matemáticas
Bastante buen motor de búsqueda integrado

Pero me di cuenta de que la versión c ++ de OpenCV3.0 está documentada en base a Doxygen y ¡no sé por qué! porque no es tan interesante como Sphinx. Sé que Doxygen puede compilar tu código y extraer tus comentarios, lo cual es una característica útil. También sé que hay bibliotecas (como respirar ) que podrían actuar como un puente entre Doxygen y Sphinx .

Ahora mis preguntas son:

¿Las alternativas de Sphinx y Doxygen son mutuamente opuestas o podrían usarse al lado?
¿Tiene Doxygen las características mencionadas de Sphinx ?
¿Qué motor de documentación ( Sphinx , Doxygen u otros motores) prefiere para mi problema?

Esta respuesta se refiere al punto 2 de su pregunta.

Sí, Doxygen tiene en parte esas características.

Puede tener fórmulas matemáticas , que se pueden representar a través de una instalación Latex local o MathJax, una biblioteca de renderizado javascript. Al igual que con Latex, estos pueden estar "incrustados" en el texto o como una unidad separada en el flujo de texto.
También incluye un motor de búsqueda .
Puede incluir imágenes fácilmente

Por ejemplo, las dos líneas a continuación agregarán la misma imagen tanto en html como en la salida generada por látex:

/image latex my_image.png "My image" width=10cm /image html my_image.png "My image" width=10cm

Creo recordar que en html, el título y el ancho se ignoran. Pero Doxygen es realmente flexible, por lo que si el comando anterior no es suficiente, simplemente puede agregarlos como código html:

<img src="my_image.png" ...additional html attributes...>

Doxygen también admite una gran cantidad de comandos html regulares que puede incluir directamente en su bloque de comentarios.

No tengo experiencia con Sphinx aparte de construir el manual de Opencv, pero lo que puedo agregar sobre doxygen (que uso día a día) es que es realmente flexible, pero esto no significa que siempre sea la mejor opción. Las páginas pueden saturarse y si el código adicional de comentarios está mal diseñado, puede interferir en su camino.

Para completar, una de las mejores exhibiciones de lo que Doxygen puede hacer (además del sitio web de Doxygen, por supuesto) es la biblioteca Eigen . Echar un vistazo.