[PySide] Shiboken - Documentation support when binding a C++ library
jcummings2 at users.sf.net
Tue Jun 5 16:22:27 CEST 2012
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
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
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
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.
More information about the PySide