Каковы основные отличия Сфинкса и Doxygen?
Я хочу подготовить документацию для коллекции проектов, модулей и библиотек в области компьютерного зрения (в основном написана на с ++). С этой целью я взглянул на документацию OpenCV и, как вы знаете, документация OpenCV 2.4.x основана на сфинкс и это было именно то решение, которое я искал. приятные особенности Сфинкса:
- Иерархическая структура модулей в семантической точке зрения. Например Фильтр Калмана это ребенок Анализ движения и отслеживание объектов модуль
- Можете добавить изображений а также математика формулы
- Довольно хорошо встраивается поисковый движок
Но я понял, что версия OpenCV3.0 для C ++ документирована на основе Doxygen и я не знаю почему! потому что это не так интересно, как сфинкс.
я знаю это Doxygen может скомпилировать ваш код и извлечь ваши комментарии, что является полезной функцией. Я также знаю, что есть библиотеки (например, дышать) который мог бы служить мостом между Doxygen а также сфинкс.
Теперь мои вопросы:
- Являются ли Sphinx и Doxygen альтернативами друг другу или их можно использовать вместе?
- Есть ли Doxygen имеют упомянутые особенности сфинкс?
- Какой движок документации (сфинкс, Doxygen или другие двигатели) вы предпочитаете мою проблему?
Решение
Этот ответ касается пункта 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, конечно), это Собственная библиотека. Взглянуть.
Другие решения