Ask Your Question
11

OpenCV 3 doxygen documentation still very counter intuitive

asked 2015-06-07 07:37:06 -0500

updated 2016-07-30 09:52:16 -0500

berak gravatar image

I would like to open up this topic to bundle together all possible suggestions that could improve the current doxygen documentation. I understand why the change has been made, but for now I find it myself quite hard to find any usefull information on it. The interface is far from intuitive like before.

Got any suggestions? Let me know!

Small wrapup of suggestions

  • Table of content on the left hand side
  • Using the complete available page size whenever possible
  • Better way to find documentation like tutorials
  • Search functionality is still improvable even tough it was worse on the old documentation
  • Samples listed are far from all the samples available
  • More similar css like style as previous interface
edit retag flag offensive close merge delete

Comments

2

I feel the same! Why did they change it?

Guanta gravatar imageGuanta ( 2015-06-07 09:19:14 -0500 )edit
1

I am new using opencv but to learn I look in opencv 2 doc and after in opencv 3 doc. May be it could be possible to improve to have something like this with table of content

LBerger gravatar imageLBerger ( 2015-06-07 09:51:27 -0500 )edit
1

I agree with you. For me, the table of contents on the left panel is missing, and it is too bad that not all the space is used.

Eduardo gravatar imageEduardo ( 2015-06-07 11:54:25 -0500 )edit
1

I also feel the same! But maybe after some time, we will enjoy it? It is still missing (at least) the table of content, and an easy access to the tutorials. Doxygen has a lot of configuration options, but it could take some time to customize it the right way. Maybe, also using more "similar" css could help in the transition...

Mathieu Barnachon gravatar imageMathieu Barnachon ( 2015-06-08 02:35:24 -0500 )edit
1

@Mathieu Barnachon of course a transition time is needed, but combining our efforts together can help the admins to get it more in the line of what the user community is expecting.

StevenPuttemans gravatar imageStevenPuttemans ( 2015-06-08 02:38:30 -0500 )edit
1

May be in function description add sample name using this function.

LBerger gravatar imageLBerger ( 2015-06-08 02:45:38 -0500 )edit
2

Steven, you say you understand why they changed it. I do not. In fact, a little earlier today, I asked this question looking for some insight as to why they changed it. My experience has been doxygen is great for API reference documentation. But it is not as good at the often more important documentation like tutorials and user manuals. OpenCV 2 with its sphinx documentation had already gone to the trouble of using sphinx, so I was surprised (and disappointed) to see they abandoned it for doxygen. I think using doxylink and/or breathe to combine doxygen with sphinx would have been better.

pwm1234 gravatar imagepwm1234 ( 2015-07-24 09:41:57 -0500 )edit

I'm also missing pdf documentation for new OpenCV.

dandur gravatar imagedandur ( 2016-07-26 02:57:04 -0500 )edit

2 answers

Sort by ยป oldest newest most voted
5

answered 2016-07-19 04:43:27 -0500

pklab gravatar image

updated 2016-07-30 09:10:02 -0500

Recently I've submitted a pull request to doxygen with the aim of improving doc readability. Basically, the proposed code generates attention-getting title using shortest header (within a specific css class for HTML doc).

I'm available to integrate the PR with your suggestions.

The project owner is seeing the disadvantage with overloaded functions because they would all get the same title (but different anchor).

It would be interesting to share opinion and suggestions on the PR conversation

EDIT Just to inform that the pull request has been merged to official Doxygen master

edit flag offensive delete link more

Comments

Great effort, thanks. It seems though that Doxygen dev is not very active/open to new suggestions...

LorenaGdL gravatar imageLorenaGdL ( 2016-07-19 11:20:33 -0500 )edit

happy to see the new doxygen style in the 3.2.0 doc. prev style / new style.

I hope users would find it more easy to read ;)

pklab gravatar imagepklab ( 2017-01-08 13:34:28 -0500 )edit
4

answered 2016-07-20 14:07:08 -0500

LorenaGdL gravatar image

I've been spending some time trying to configure Doxygen to add needed features. I've been quite sucessful in some things, and also I've realized that other things are likely to turn into impossible dreams.

Anyway, the only way to find out the limits is to combine our efforts and start making some changes. For that reason I have created a dedicated branch in my forked OpenCV Github repo. I think we can gather there to collect opinions and modifications, with the goal of ultimately making an official PR. The discussion thread can be found here, including a TO-DO list. You will also find the first updates, including the left navigation bar!

So come join me to build powerful and useful docs!

And to end this post, buzzes to all the people who has commented in this thread (I hope you don't mind), to gather as many opinions/help as possible! @StevenPuttemans @Guanta @LBerger @Eduardo @Mathieu Barnachon

P.s. I find Github a much more convenient way to continue the discussion and integrate changes. If anyone has a better suggestion, let me know

edit flag offensive delete link more

Comments

I prefer Github for working on stuff like this also. Will get back to you if I have time to pitch in!

StevenPuttemans gravatar imageStevenPuttemans ( 2016-07-22 05:40:47 -0500 )edit
Login/Signup to Answer

Question Tools

6 followers

Stats

Asked: 2015-06-07 07:37:06 -0500

Seen: 953 times

Last updated: Jul 30 '16