Каковы основные отличия Sphinx и Doxygen?

Я хочу подготовить документацию для коллекции проектов, модулей и библиотек в области компьютерного видения (в основном написанных на С++). С этой целью я посмотрел документацию OpenCV и, как вы знаете, документация OpenCV 2.4.x основана на Sphinx, и это было точное решение, которое я искал для. приятными чертами Сфинкса являются:

Иерархическая структура модулей в семантической точке зрения. Например, Kalman Filter является дочерним модулем Motion Analysis и Object Tracking.
Вы можете добавить изображения, а также математические формулы
Довольно хорошая встроенная поисковая система

Но я понял, что версия С++ для OpenCV3.0 документирована на основе Doxygen, и я не знаю почему! потому что это не так интересно, как Сфинкс. Я знаю, что Doxygen может скомпилировать ваш код и извлечь ваши комментарии, которые являются полезной функцией. Я также знаю, что есть библиотеки (например, дышать), которые могут выступать в качестве моста между Doxygen и Sphinx.

Теперь мои вопросы:

Есть альтернативы Sphinx и Doxygen друг от друга или они могут использоваться вместе?
Есть ли у Doxygen упомянутые особенности Sphinx?
Какой механизм документации (Sphinx, Doxygen или другие двигатели) вы предпочитаете для моей проблемы?

Ответ 1

В этом ответе указан пункт 2 вашего вопроса.

Да, Doxygen частично имеет эти функции.

У вас могут быть математические формулы, которые могут отображаться либо при локальной установке Latex, либо в MathJax, в библиотеке рендеринга javascript. Как и в случае с латекс, они могут быть либо "встроены" в текст, либо как отдельный блок в текстовом потоке.
Он также включает поисковую систему.
Вы можете легко включить изображения.

Например, две приведенные ниже строки добавят одно и то же изображение как в html, так и в латексном выражении:

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

Думаю, я помню, что в html заголовок и ширина игнорируются? Но Doxygen действительно гибкий, поэтому, если вышеприведенной команды недостаточно, вы можете просто добавить их в виде html-кода:

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

Doxygen поддерживает также множество обычных команд html, которые вы можете напрямую включить в свой блок комментариев.

У меня нет опыта работы с Sphinx, кроме создания руководства Opencv, но то, что я могу добавить о doxygen (которое я использую изо дня в день), состоит в том, что он действительно гибкий, но это не значит, что он всегда лучший выбор. Страницы могут стать загроможденными, а если дополнительный код комментария плохо разработан, он может помешать вам.

Для полноты одной из лучших демонстраций того, что может сделать Doxygen (помимо веб-сайта Doxygen), является