Ask Your Question
5

Why did OpenCV 3 change its documentation tool from sphinx to doxygen

asked 2015-07-24 08:31:11 -0500

pwm1234 gravatar image

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.

Thanks!

edit retag flag offensive close merge delete

Comments

I agree with stackoverflow members, it is more to this QA forum

thdrksdfthmn gravatar imagethdrksdfthmn ( 2015-07-24 09:16:27 -0500 )edit
1

You can also contribute to this topic.

Eduardo gravatar imageEduardo ( 2015-07-24 09:21:19 -0500 )edit

1 answer

Sort by ยป oldest newest most voted
7

answered 2015-07-27 09:12:48 -0500

mshabunin gravatar image

Main advandages:

  • 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)

Main disadvantages:

  • 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)

Additional advantages:

  • 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)
edit flag offensive delete link more

Comments

Which are all great advantages :D BUT we should try to make the look and feel more natural. The largest problem now is an easy way to find access to tutorials and manuals for modules if you ask me :)

StevenPuttemans gravatar imageStevenPuttemans ( 2015-07-28 04:10:32 -0500 )edit

Doesn't all tutorials can be directly accessed from the "Related pages" page?

http://docs.opencv.org/master/pages.html

Or did you mean full-text search?

mshabunin gravatar imagemshabunin ( 2015-07-28 04:27:27 -0500 )edit

Yes it can ... but that is not a natural way of looking for tutorials :D

StevenPuttemans gravatar imageStevenPuttemans ( 2015-07-28 05:04:10 -0500 )edit
Login/Signup to Answer

Question Tools

3 followers

Stats

Asked: 2015-07-24 08:31:11 -0500

Seen: 3,466 times

Last updated: Jul 27 '15