[PySide] Shiboken - Documentation support when binding a C++ library

[John Cummings]

Yann Lanthony <yann.lanthony at ...> writes:

> However, I have trouble understanding how I can also retrieve my C++ doxygen-
style documentation as python docstrings, to be able to print functions doc at 
runtime with help(myFunction).
> I am working on Windows (64bits) and I have compiled shiboken (and pyside) 
with docstring support (well, I linked libxml2 and libxslt which seem to be the 
2 documentation related libraries). 
> 
> 
> Is it at least possible to do something like that with the current version of 
shiboken (1.1.1) ?
> 

Yann, the short answer is no, at least not the form you and I would like. The 
docstring related CMake settings (see my previous posts) are actually to produce 
sphinx-compatible .rst files. Apparently sphinx is somewhat like doxygen in that 
it expects docstrings to be formatted in a certain way and then you can output 
the documentation in different formats (HTML, PDF, etc.). Sphinx is apparently  
the python way of doing it.

However, I did manage to cobble the pieces together to produce some .rst files 
using my existing doxygen-formatted documentation. To do that, I did the 
following (perhaps this should be a wiki entry or did I just miss the existing 
one?):

1. Make sure that libxml2 and libxslt are installed and that DISABLE_DOCSTRINGS 
is set to OFF (I believe that is the default if CMake finds libxml2 and 
libxslt). Build and compile shiboken as usual. Doing so essentially allows the -
-generator-set argument to accept "qtdoc" as a value for generating 
documentation.

2. Run doxygen over your C++ library with the XML output enabled. Be sure to 
note the output directory for the XML files.

3. Run shiboken in the same way you would for generating the bindings but add 
the following additional options:
   * --generator-set=qtdoc This adds a documentation "generator"
   * --doc-parser=doxygen  This sets the documentation parser to assume doxygen 
formatting. By default, qtdoc formatting is assumed.
   * --library-source-dir  Set this to the top level of your C++ source tree.
   * --documentation-data-dir Set this to the doxygen XML output directory.
There are also more options available. See QtDocGenerator::options for a better 
description or it turns out you can run "shiboken --help --generator-set=qtdoc" 
and it will display these options (did I miss a page on the wiki for this 
option?)

You will then have .rst files for your library. Unfortunately, at this time, it 
doesn't grab as much of the doxygen documentation as I would like, but I do have 
the source code and may make changes.

This still doesn't address your/our initial question. I'll post another email 
about that topic in particular.