Why did the OpenCV team decide to change its documentation tool from sphinx to doxygen? I like the sphinx generated documentation and thought OpenCV 2 had both nice online and printed documentation that was relatively easy to author. I have searched but have not seen a discussion of why change to doxygen.
I asked this same question on StackOverflow, but it was closed as being off-topic. I am hoping to get some insight from this forum.
- with doxygen it is easier to maintain documentation and to support contrib modules
- reference is always consistent with the code (for example, it can not contain function which have been deleted)
- generator has some built-in correctness checks (for example, if some function have several documented parameters and several undocumented, then generator will produce a warning)
- no pdf documentation yet (doxygen supports this output, but it needs some tuning)
- no java/python documentation yet (doxygen can produce xml, but some cooperation with javadoc/pydoc/epydoc is needed)
- basic search is limited to entity identifiers only, i.e class/method/namespace/tutorial names (Google custom search can be used for full-text search)
- doxygen can produce help in some additional formats: rtf, chm (Compiled HTML), qch (Qt help), Eclipse help, XCode DocSets. However, all these methods should be additionally configured and tuned
- basic search works without web server (one can build and use html reference on local machine)
- formula rendering uses MathJax client-side technology
- html documentation can be built really fast comparing to sphinx (1 min vs. 31 min)