32

I want to prepare a documentation for a collection of projects, modules and libraries in the field of computer vision (mostly written in c++). To this end I had a look on OpenCV documentation and as you may know OpenCV 2.4.x documentation is based on Sphinx and It was the exact solution that I was seeking for. the nice features of Sphinx are:

  1. Hierarchical structure of modules in semantic point of view. For example Kalman Filter is a child of Motion Analysis and Object Tracking module
  2. You can add images and also mathematics formulas
  3. Pretty good embedded search engine

But I realized that the c++ version of OpenCV3.0 is documented based on Doxygen and I don't know why! because it is not as interesting as Sphinx. I know that Doxygen can compile your code and extract your comments which is an useful feature. I also know that there are libraries (like breathe) which could act as a bridge between Doxygen and Sphinx.

Now my questions are:

  1. Are Sphinx and Doxygen alternatives of each other or they could be used alongside?
  2. Does Doxygen have the mentioned features of Sphinx?
  3. Which documentation engine (Sphinx, Doxygen or other engines) do you prefer for my problem?
bad_coder
  • 11,289
  • 20
  • 44
  • 72
Ali Mirzaei
  • 1,496
  • 2
  • 16
  • 27
  • The Sphinx says it is a Python documentation tool. I know Doxygen can parse C++ language. – Thomas Matthews Jul 22 '15 at 19:18
  • 1
    Exactly this is my problem. But I am wondering how is the c++ version of OpenCV documented using Sphinx!! – Ali Mirzaei Jul 22 '15 at 19:28
  • This is an excellent, but perhaps a little broad, question. It prompted me to ask http://stackoverflow.com/questions/31594254/why-did-opencv-3-change-its-documentation-tool-from-sphinx-to-doxygen. As for how OpenCV2 is documented with sphinx, it uses the sphinx c++ domain, and is relatively straightforward to follow in the cmake build scheme. – Phil Jul 23 '15 at 17:31

1 Answers1

16

This answer addresses point 2 of your question.

Yes, doxygen partly has those features.

  • You can have math formulas, that can be rendered either through a local Latex install, or through MathJax, a Javascript rendering library. As with Latex, these can be either "embedded" into text, or as a separate unit in the text flow.
  • It also includes a search engine.
  • You can easily include images.

For example, the two lines below will add the same image both in html and latex generated output:

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

I think I recall that in html, caption and width are ignored ? But Doxygen is really flexible, so if the command above isn't enough, you can just add them as html code:

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

Doxygen supports also a lot of regular html commands that you can directly include in your comment block.

I have no experience with Sphinx other than building Opencv manual, but what I can add about Doxygen (that I use on a day to day basis) is that it is really flexible, but this doesn't mean it's always the best choice. Pages can get cluttered and if the comment additional code is badly designed, it can get in your way.

For completeness, one the best showcases of what doxygen can do (besides the Doxygen web site of course), is the Eigen library. Take a look.

kebs
  • 6,387
  • 4
  • 41
  • 70