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

[Hugo Parente Lima]

On Tuesday, June 05, 2012 02:22:27 PM John Cummings wrote:
> 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.

The doxygen backend still incomplete, because we had work mostly on qtdoc 
backend to support the PySide documentation.
 
> This still doesn't address your/our initial question. I'll post another
> email about that topic in particular.

About docstrings, it's not supported, however it's not hard to add such 
support, you just need to decide what to do with documentation of function 
overloads.
 
> _______________________________________________
> PySide mailing list
> PySide at qt-project.org
> http://lists.qt-project.org/mailman/listinfo/pyside
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 198 bytes
Desc: This is a digitally signed message part.
URL: <http://lists.qt-project.org/pipermail/pyside/attachments/20120605/4884c5b8/attachment-0001.sig>