web-dev-qa-db-fra.com

Quelles sont les principales différences entre Sphinx et Doxygen?

Je souhaite préparer une documentation pour une collection de projets, modules et bibliothèques dans le domaine de la vision par ordinateur (principalement écrits en c ++). À cette fin, j'ai jeté un œil à la documentation OpenCV et comme vous le savez peut-être OpenCV La documentation 2.4.x est basée sur Sphinx et c'était la solution exacte que je cherchais. les fonctionnalités de Nice de Sphinx sont:

  1. Structure hiérarchique des modules au point de vue sémantique. Par exemple Kalman Filter est un enfant du module Motion Analysis and Object Tracking
  2. Vous pouvez ajouter des images ainsi que des formules mathématiques
  3. Assez bon moteur de recherche intégré

Mais j'ai réalisé que la version c ++ d'OpenCV3.0 est documentée sur la base de Doxygen et je ne sais pas pourquoi! car ce n'est pas aussi intéressant que Sphinx. Je sais que Doxygen peut compiler votre code et extraire vos commentaires, ce qui est une fonctionnalité utile. Je sais aussi qu'il existe des bibliothèques (comme respirer) qui pourraient servir de pont entre Doxygen et Sphinx.

Maintenant mes questions sont:

  1. Sphinx et Doxygen sont-ils alternatifs ou pourraient-ils être utilisés en parallèle?
  2. Doxygen a-t-il les caractéristiques mentionnées de Sphinx?
  3. Quel moteur de documentation ( Sphinx, Doxygen ou d'autres moteurs) préférez-vous pour mon problème?
c++opencvpython-sphinxdoxygendocumentation-generation
20
Ali Mirzaei

Cette réponse répond au point 2 de votre question.

Oui, doxygen possède en partie ces caractéristiques.

  • Vous pouvez avoir formules mathématiques , qui peuvent être rendues soit via une installation Latex locale, soit via MathJax, une bibliothèque de rendu Javascript. Comme avec Latex, ceux-ci peuvent être soit "intégrés" dans le texte, soit comme une unité distincte dans le flux de texte.
  • Il comprend également un moteur de recherche .
  • Vous pouvez facilement inclure des images .

Par exemple, les deux lignes ci-dessous ajouteront la même image en sortie générée en html et en latex:

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

Je pense que je me souviens qu'en html, la légende et la largeur sont ignorées? Mais Doxygen est vraiment flexible, donc si la commande ci-dessus ne suffit pas, vous pouvez simplement les ajouter en tant que code html:

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

Doxygen supporte également beaucoup de commandes html régulières que vous pouvez inclure directement dans votre bloc de commentaires.

Je n'ai aucune expérience avec Sphinx autre que la construction du manuel Opencv, mais ce que je peux ajouter à propos de Doxygen (que j'utilise quotidiennement), c'est qu'il est vraiment flexible, mais cela ne signifie pas que c'est toujours le meilleur choix. Les pages peuvent être encombrées et si le code supplémentaire de commentaire est mal conçu, il peut vous gêner.

Pour être complet, l'une des meilleures vitrines de ce que doxygen peut faire (en plus du site Web Doxygen bien sûr), est la bibliothèque propre . Regarde.

9
kebs