DISCUSSION - 3.x Doxygen docs improvements

[LorenaGdL]

This is the main discussion area for suggestions/improvements regarding OpenCV 3.x Doxygen documentation. Published documentation with Doxygen system remains counter-intuitive and lacks important features. This git repo (branch docs-doxygen) aims to combine opinions and efforts of OpenCV users in order to give docs a revamp. Once we have stable major updates, we will transfer everything to official repo through a PR.

How to contribute

• Give your opinion about proposed changes or suggest a new one (comment in this issue)
• Make Pull Requests by forking the docs-doxygen branch and commiting changes
• Spread the word! Let's involve as many users as possible

  Suggestions / TO-DO list

This is a first reference list based on this forum thread and some personal opinions. It will be updated with completed tasks and new tasks based on the discussion

• General look / contents
  • [x] Table of content on the left hand side - completed
  • [x] Tutorials easier to find (new navigation tab) - completed
  • [x] Cleaner interface (hidden advanced tabs, better grouping) - completed
  • [ ] Using complete available page size whenever possible (is this still an issue?)
  • [ ] Search functionality is still improvable (note: nothing to do via Doxygen configuration afaik)
  • [ ] Samples listed are far from all the available samples (note: currently listed samples are the ones linked in the docs. All samples could be inserted with medium effort)
  • [ ] Improved CSS stylesheet (closer to previous docs?)
  • [ ] Inner elements re-ordering: I don't particularly like the way generated docs are ordered (enums before functions, and things like that. This could be discussed)
• Inner Doxygen style (probably needing Doxygen source code modification
  • [ ] Enums: why are enums information "duplicated" inside class docs? First, a simple enum list is provided, showing numerical values. Later on, enums are again mentioned, now without the numerical value but with the inline comment of each possible option. Couldn't both thing be combined together? (I haven't found such thing via config options)
• Needed general documentation updates
  • [ ] General introduction to OpenCV: update from 2.0 to 3.0 (references, modules list (with automatic generation ideally), etc.)
  • [ ] FAQs: mention forum, how to contribute guide, etc.

    Brief changelog

07/20/2016 - Discussion opened 07/20/2016 - Navigation left-sidebar, new tab structure (cleaner, "hidden" advanced tabs), easy-access to tutorials (@LorenaGdL)

Related stuff

• OpenCV forum thread
• Doxygen engine modification to display shorter names by @PkLab

[LorenaGdL]

I've already done a bunch of modifications, by tweaking the different Doxygen configuration files

Left-side navigation bar

One of the most wanted features to improve usability. Bar width is set to a configurable default value, but it can be resized by the user. Top navigation bar is kept anyway (it could be removed)

General re-structure of tabs/lists, to get a cleaner/easier interface

• Namespaces, Classes and Files navigation lists grouped/hidden under "Advanced" tab: I very much doubt 99% of people use such lists - they're complex. Maybe very advanced users or core dev may find them useful, and that's why I kept them, but they also take space and confuse regular users. I still remember the first time I entered the Doxygen docs, and I didn't know where to start from with all that tabs! This way, the "Modules" tab is sort of highlighted
• Collapsed lists: all lists are collapsed by default to minimum detail. In the official docs, some lists are almost-fully expanded, cramping the space and limiting a clear global overview (not sure if what I changed is fully suitable/working in all situations, further testing might be needed).
• Tutorials: OpenCV tutorials now have their own tab, so that they're easier to access/find. Moreover, now it is easily to realize that there are C++, Python and Contrib tutorials. This modification also includes a small reorganization of the source doc/tutorials folders.
• Related pages: they were given a way too much relevant position in the nav bar, so now they more to the right side. Apart from that, it was a collection of pages with no order, no references, kind of chaotic. Now, they are simply the extra .markdown pages found in the modules/X/doc folders.
• Todo, deprecated, and bibliography lists: related to previous point, right now Todo lists and Deprecated info is not included anywhere. They could be put in the Related Pages, Main Page or other additional page (give opinions - I would omit Todo list in any case). Bibligraphy is indexed in main page, but could be highligthed if needed.

The best way to test all these features if to fork the branch, generate the docs and navigate. But some screenshots showing new feel:

Opinions, suggestions and further improvements welcomed! :smile:

[StevenPuttemans]

@LorenaGdL omg this is great! How about getting some of the core devs involved and see where this can take us!

@mshabunin and @alalek what do you guys think. Would devs consider using these updated doc packages to improve usability?

[alalek]

/cc @vpisarev

[PkLab]

You get started a really great work ! here some (randomly) points:

• Overall organization/hierarchy should be defined for pages, markdown intros, modules. Following current organization you had distributed doxygen pages into tutorials but most of them are general infos unrelated to a programming language (eg. Understanding SVM is in Tutorials>Python ?!?)...
• Merge samples and tutorials ?
• Use \snippet instead of \code (see Issue #6938)
• Elements re-ordering: something is feasible with DoxygenLayout.xml
• About Doxygen modification I think that we should use official doxygen distro. Thus our only chance is to propose PRs to doxygen... as I did, but as you said Doxygen dev is not very active/open to new suggestions, maybe some support from OpenCV might be useful
• About "complete available page size" I don't like it so much because on wide screen you would have very long lines... it's just my opinion
• Make the doc available in PDF

Finally, a big dream, it would interesting to investigate feasibility to use Doxygen as XML generator, to develop an XML parser to DB than a Django app to manage the docs as we like... maybe to integrate into AskBot :)

[mshabunin]

I have one comment related to left-side navigation bar. When it is enabled, returning back in browser history works incorrectly, that is why I disabled it initially. My scenario is as following:

• go to some long page, e.g. http://docs.opencv.org/master/d0/de1/group__core.html#gsc.tab=0
• scroll down to some function
• click some link (for example referring to Mat or UMat class in function parameter list)
• push Back in your browser

With nav-tree: return to the top of previous page Without nav-tree: return to the same place of the previous page

I'm not sure whether it can be fixed in doxygen or via some css/html addons on our side, but it is really annoying.

Also, TODO list, Deprecated list and Bibliography pages can be found on the Related Pages tab.

I definitely like ideas with gathering all pages from doc folders and Tutorials quick link.

[LorenaGdL]

@mshabunin

1) I can reproduce back button issue on Chrome, but not on Firefox (which is my default browser, and that's why I didn't notice this before). It seems Chrome has some general issues with this regard, related to navigation with JS mainly. I'll see if I can find a workaround...

2) About TODO list, Deprecated list and Bibliography: small misunderstanding here. Yes, official OpenCV docs include such pages in the Related Pages section. I was just pointing out that in my current modified (and temporal) version they are not included there, but they could (or they could have another spots within docs depending on our needs/opinions).

[PkLab]

1) I can reproduce the back button issue on Firefox too

2) I'm trying to work on overall organization/hierarchy. A kick off question (Should I start from "module/code" or "argument/overview" ? ). A fake question but it makes me clear that

1. We are talking about a deep reorganization of the doc.
2. This work would require multiple iterations On the other side doc still very counter intuitive and some effort is needed

I think that the OpenCV members should be actively involved to avoid wrong way or unwanted/useless effort. For example, it might be useful

• to move this fork under an opencv branch
• to make generated doc navigable maybe under docs.opencv.org/branch
• to activate a chat (smart communication)
• :grey_question: to expand commit rights to group of well known github users just for this branch (smart modification)

[mshabunin]

First of all, let's not spend too much effort on this task at this moment. We have at least one GSoC project with possible major documentation update. I suggest deciding what does counter intuitive mean in this case and how should intuitive documentation look like. Anyone can give examples of "nice" documentations from thier point of view (preferably from C/C++ libraries). After that we can choose general layout and useful features to be implemented and integrate them through several pull requests.

• I guess we will not add an additional branch for documentation changes in main repository
• it is possible to preview generated docs for each pull request on buildbot
• we will discuss possibility of creating an official chat on Gitter
• AFAIK GitHub does not allow to set user rights for specific branch

From my point of view we should separate each module docs into documentation articles, tutorials and reference. So most text from current reference should be moved to several well-written pages:

• :page_facing_up: Module ALPHA General description

  • :page_facing_up: Functionality block A

  You can do this and that with functionX and functionY (+some formulas, images, papers references, etc.)

  • :page_facing_up: Functionality block B

  Something similar here

  • :page_facing_up: Functionality block B-1

    Some more interesting things

  • :page_facing_up: Tutorial A

  Moved here, includes python and java

  • :page_facing_up: Tutorial B

  Moved here too

  • :link: Code reference (Doxygen module)

  Each function has minimal description, link to corresponding text page, good argument description, notes on implemetation

In this scenario main challenge will be in text writing and organic themes composing and main problem will be in keeping text consistent with actual API (but it will probably be easier than in Sphinx docs).

[StevenPuttemans]

Hi guys, nice to see the discussion going, but lets not forget that there was already a topic with tons of input ideas here: https://github.com/opencv-infrastructure/answers.opencv.org/issues/21

Lets not forget to try and integrate features discussed there too if possible :)

@mshabunin In my opinion, the old sphynx layout was more readable as to code, except for the missing declarations (overloads for example) and the terrible search function. I guess doxygen is too clean (no better word to describe yet ...) for the moment?

[PkLab]

A small news from doxygen: My PR to display shorter names has been merged. Here is a screenshot with new doxygen

[StevenPuttemans]

:+1: Great work @PkLab!

[PkLab]

Looking at @mshabunin's schema, the General descriptions and Functionalities should be done with \pages while code reference with \defgroup. This would requires

• a new page file for each module/submodules thus Index of pages and index of modules
• most of current modules description and tutorials should be moved to the related page
• a double way should be created and maintained between descriptions and code. Maybe something can be done with CMake.

This looks a really big effort and would requires a lot of new .markdown files and will changes all <module>.hpp files

Because most of the useful docs and theory are in the tutorials. I think we should wait for the GSoC project before to work on overall documentation.

We could start with small modifications

1. We could select a single module as test base to implement the new schema. HighGUI ?
2. I think that the nav-tree is really useful despite of the back button issue
3. I've changed DoxygenLayout.xml so to have the following order
   • Detailed Description
   • Sub Modules
   • Classes , Functions, ...

@mshabunin

it is possible to preview generated docs for each pull request on buildbot

Is buildbot available also for this fork ? or we have to submit a PR to opencv directly to share a preview

[mshabunin]

@PkLab , no, buildbot does not check forked repositories, the PR to central repository should be created or some other hosting used for generated documentation preview.

highgui probably is not the best candidate for preview as it does not contain algorithms, probably. I think ml could be transformed with less effort:

• it already have all algorithms described on separate page
• it has specific tutorials in C++ and Python
• it has almost all entities documented

[StevenPuttemans]

Maybe, if you are looking at making stuff more universal, I could pitch in if you want stuff to get translated to tutorials or such :) not really into the documentation coding buisiness, but writing documentation is achievable!

[mshabunin]

I've created a documentation improvement plan, I hope the described steps will make the documentation more intuitive. Looks like this discussion is the most appropriate place for review, so please take a look and provide your comments.

[StevenPuttemans]

Guys, might be nice to see that there is an application for GSoC for documentation improvement right here: https://groups.google.com/forum/#!topic/opencv-gsoc-2017/6X5h5YbT470

It would be nice to get this guy in on the discussion and convince him to implement some of the suggestions we have.

[karandeepdps]

Now I understood what you are asking for.It would be good to improve using these methods.I have already included this in my GSoCa application.If you want any additional changes let me now.I am so desperate to contribute. I have successfully made a pull request for tiny-dnn tutorial. https://groups.google.com/forum/#!topic/opencv-gsoc-2017/WLErLv8bVng

[karandeepdps]

Following changes need to be implemented/Improved. Quick search which can be done using https://www.stack.nl/~dimitri/doxygen/manual/extsearch.html No PDF documentation and cheatsheet: This can be made easily not an issue. Code samples (samples/cpp) are not documented or represented other way:We can add comments to existing cpp codes to explain functions.

[karandeepdps]

We can also use Graphviz to draw diagrams or flowcharts.

[StevenPuttemans]

Okay so @karandeepdps

• Adding the suggestions from this page (at least the ones that seem doable to you) is indeed a good contribution to your application.
• Make it clear what you are going to tackle and how you are going to implement the suggested changes.
• There is no reason to flood this topic for now, keep in mind that you can edit and update given answers.
• If you made a tiny-dnn documentation pull request, do not forget to add that one to your application.

We can also use Graphviz to draw diagrams or flowcharts.

Thats indeed a possibility, however that is again a new dependency for OpenCV. This might be a no-go for OpenCV devs, but to be sure, you will have to await your feedback from OpenCV adminds/core devs.

Again, the goal now is to have your application as good as possible so that your chances of getting accepted are as high as possible.

[PkLab]

Request for a better doc is still alive

I think this is an effort that should be done by the community and the OpenCV team.

I seeing 2 points point about doc:

1. General organization, java and python version tutorial, examples ecc...
2. Number of functions and classes coming with poor doc or undocumented at all.

About Point 1, this discussion is working well but is stale ?!

Point 2 is quite relevant... Just to give a number... Dogygen generates about 16K warnings like ...is not documented Sure not all 16K are relevant but my impression this number is increasing since OpenCV3

Hint: Doc for the committed code must be provided at commit time under a well defined doc organization ;)

[StevenPuttemans]

Hint: Doc for the committed code must be provided at commit time under a well defined doc organization ;)

Actually that is a hard dependency. New functionality is NOT accepted when added to the library without documentation. So not really seeing an issue there. There is just soooo much code which is not documented yet :dagger:

About general organization of the tutorials and examples, let's await the GSoC of carthucho and work on top of his basis.

[PkLab]

I know it's a hard dependecy but if there is so much UNdocumented code it means that is not so hard.

For example

• softfloat has been added on May 29, 2017 but it doesn't contains a line of doc SoftFloat
• ELU layer, added few days ago here https://github.com/opencv/opencv/pull/9285 with empty doc or cite.
• forwardSlice?

[StevenPuttemans]

I have to agree on the newly added functions. It seems getting them in was more important that maintaining conditions like documentation, tests, ... The softfloat is some kind of side thing, because I am unsure how you would document a new data type :D

@mshabunin is there a reason why we do not enforce documentation anymore on pull requests.

@dkurt and @arrybn is it possible to add documentation whenever you are adding new stuff into dnn module and layers? It seems you guys are mainly focussing that module right now.

[PkLab]

It seems getting them in was more important that maintaining conditions like documentation, tests

It's my feeling too

The softfloat is some kind of side thing, because I am unsure how you would document a new data type

they found a lot to say about softfloat http://www.jhauser.us/arithmetic/SoftFloat-3/doc/SoftFloat.html :wink:

[mshabunin]

@StevenPuttemans , to start automated checking of documentation we have to fix all existing issues (missing docs) first. Currently only basic validation is done: wrong links, parameters, etc.

[PkLab]

@mshabunin But automation can only check presence/absence.

I think that, before to accept the PR, an overall evaluation of doc related to the receiving code should be done by human. In special case of behavioural changes or modification.

To start with automation I suggest to enable warning in doxygen...

EXTRACT_ALL = NO  ; # Note: YES will also disable the warnings
EXTRACT_PRIVATE = YES
EXTRACT_STATIC = YES
WARNINGS = YES
WARN_IF_UNDOCUMENTED = YES
WARN_IF_DOC_ERROR = YES
WARN_NO_PARAMDOC = YES

...and check for any msg related to the commit. Maybe this check be done automatically

[alalek]

Basic softfloat documentation is upcoming here: opencv/opencv#9329

[PkLab]

@alalek nice to see.

Using this PR as example I would underline that not all members have doc. Following @mshabunin

we have to fix all existing issues (missing docs) first

I think that commits should not produce any new missing doc. Where doc is useless we might write something like \brief named