New documentation

[Simon Friedberger-5]

Hi everybody,
while I think that the new sphinx generated documentation is a lot better then
the wiki was I think we should reconsider the choice of sphinx for the new
documentation.

I'm not sure if everybody has already made up his mind about this but I'm
starting a list of advantages for each anyway. I hope you guys will comment and
add points.

Doxygen:
        - the documentation cannot lie
          e.g. right now the documentation says the following
          cvCalcOpticalFlowHS(const CvArr* prev, ...
          while the true definition is
          cvCalcOpticalFlowHS( const void* srcarrA, ...

        - function parameters don't have to be repeated three times like in
          the current documentation (for the function call in different
          languages and the detailed description)

        - it is shown which include file is needed for something

        - it's a lot nicer to edit then tex

        - it might encourage programmers to actually document their code when
          they write it

Sphinx:
        - the search is javascript so it works without webserver/php

        - the existing documentation can be used (!)

Maybe Sphinx can just create documentation from code, too and this is all a
moot point. Who knows more about this?

It would probably be best to have some kind of transitional solution and a tool
that creates in code documentation from the existing one or at least points out
errors and missing parts.

I would like to know what the more sphinx-educated folks think about this.

Best
Simon

------------------------------------------------------------------------------
Let Crystal Reports handle the reporting - Free Crystal Reports 2008 30-Day
trial. Simplify your report design, integration and deployment - and focus on
what you do best, core application coding. Discover what's new with
Crystal Reports now.  http://p.sf.net/sfu/bobj-july
_______________________________________________
Opencvlibrary-devel mailing list
Opencvlibrary-devel@...
https://lists.sourceforge.net/lists/listinfo/opencvlibrary-devel

[John Stowers-2]

Maybe Sphinx can just create documentation from code, too and this is all a
moot point. Who knows more about this?

I have been using Breath (http://github.com/michaeljones/breathe/tree/master), which is a Doxygen -> Sphinx bridge, in my project. While the tool is not perfect (i.e. it only supports function and class annotations ATM), the author is responsive when I ask him for enhancements.

It basically adds some additional sphinx commands that can reference functions and classes, the formatted doxygen is inserted into the sphinx output

John

It would probably be best to have some kind of transitional solution and a tool
that creates in code documentation from the existing one or at least points out
errors and missing parts.

I would like to know what the more sphinx-educated folks think about this.

Best
Simon

------------------------------------------------------------------------------
Let Crystal Reports handle the reporting - Free Crystal Reports 2008 30-Day
trial. Simplify your report design, integration and deployment - and focus on
what you do best, core application coding. Discover what's new with
Crystal Reports now.  http://p.sf.net/sfu/bobj-july
_______________________________________________
Opencvlibrary-devel mailing list
Opencvlibrary-devel@...
https://lists.sourceforge.net/lists/listinfo/opencvlibrary-devel

------------------------------------------------------------------------------
Let Crystal Reports handle the reporting - Free Crystal Reports 2008 30-Day
trial. Simplify your report design, integration and deployment - and focus on
what you do best, core application coding. Discover what's new with
Crystal Reports now.  http://p.sf.net/sfu/bobj-july
_______________________________________________
Opencvlibrary-devel mailing list
Opencvlibrary-devel@...
https://lists.sourceforge.net/lists/listinfo/opencvlibrary-devel

[Vadim Pisarevsky]

Hello,

There should be one main source for the reference manual, regardless of the final representation (PDF or HTML/Wiki). After careful evaluation we went with Latex, because in the future we want to make a decent OpenCV reference manual with formulas, diagrams, references etc. So far only TeX can produce typographic-quality PDF, besides, many our users are familiar with it.

Sphinx sources are generated from Latex, so we edit only .tex files.

Doxygen usually produces too shallow documentation, i.e. the output is just a little bit more than a good class browser could provide. Still, putting more descriptive comments to the header files and the source code may be a good idea (and a better Doxygen output will be a side effect of this effort), it can be done in parallel with improving the main documentation if there are volunteers to do that. But I must notice that an obsolete, incorrect or misplaced (due to code rearrangements) comment can make code comprehension more difficult than lack of the comment, therefore, 1) we should not overdo it 2) we should keep the comments up-to-date. 

Regards,

Vadim

On Fri, Aug 21, 2009 at 1:53 AM, Simon Friedberger <simon%2Bocd@...> wrote:

Hi everybody,
while I think that the new sphinx generated documentation is a lot better then
the wiki was I think we should reconsider the choice of sphinx for the new
documentation.

I'm not sure if everybody has already made up his mind about this but I'm
starting a list of advantages for each anyway. I hope you guys will comment and
add points.

Doxygen:
       - the documentation cannot lie
         e.g. right now the documentation says the following
         cvCalcOpticalFlowHS(const CvArr* prev, ...
         while the true definition is
         cvCalcOpticalFlowHS( const void* srcarrA, ...

       - function parameters don't have to be repeated three times like in
         the current documentation (for the function call in different
         languages and the detailed description)

       - it is shown which include file is needed for something

       - it's a lot nicer to edit then tex

       - it might encourage programmers to actually document their code when
         they write it

Sphinx:
       - the search is javascript so it works without webserver/php

       - the existing documentation can be used (!)

Maybe Sphinx can just create documentation from code, too and this is all a
moot point. Who knows more about this?

It would probably be best to have some kind of transitional solution and a tool
that creates in code documentation from the existing one or at least points out
errors and missing parts.

I would like to know what the more sphinx-educated folks think about this.

Best
Simon

------------------------------------------------------------------------------
Let Crystal Reports handle the reporting - Free Crystal Reports 2008 30-Day
trial. Simplify your report design, integration and deployment - and focus on
what you do best, core application coding. Discover what's new with
Crystal Reports now.  http://p.sf.net/sfu/bobj-july
_______________________________________________
Opencvlibrary-devel mailing list
Opencvlibrary-devel@...
https://lists.sourceforge.net/lists/listinfo/opencvlibrary-devel

------------------------------------------------------------------------------
Let Crystal Reports handle the reporting - Free Crystal Reports 2008 30-Day
trial. Simplify your report design, integration and deployment - and focus on
what you do best, core application coding. Discover what's new with
Crystal Reports now.  http://p.sf.net/sfu/bobj-july
_______________________________________________
Opencvlibrary-devel mailing list
Opencvlibrary-devel@...
https://lists.sourceforge.net/lists/listinfo/opencvlibrary-devel