[Qgis-developer] Sip flag to generate docstrings

[Larry Shaffer]

Hi Gary,

On Sun, Feb 19, 2012 at 9:19 PM, Gary Sherman <gsherman at geoapt.com> wrote:
> ...
>>> Could you post a link to the generated PyQGIS API file? (In case I
>>> miserably fail at compiling it again.) Like to test it out.
>
> Here you go:
> http://geoapt.com/files/pyqgis.api

Thanks! It works great. Even though it is only part of the API, at
least it's the GUI calls, a real time saver on typing and looking up,
once you have a clue about them.

http://dl.dropbox.com/u/4058089/qgis/Eric4-autocomplete_pyqgis-gui.png
http://dl.dropbox.com/u/4058089/qgis/Eric4-call-tip_pyqgis-gui.png

On Sun, Feb 19, 2012 at 9:44 PM, Gary Sherman <gsherman at geoapt.com> wrote:
> ...
> Unfortunately sip is run in three passes (I think) so the file is getting overwritten. It only contains the results of the last run. Not sure how to manage that since there is one flag setting in CMake.

I thought that might be a problem but never got to your success with
it. Now I see that my compiles of QGIS are flawed in a different way,
which made me think it was the sip -a option. Can now test this
further sometime.

I see the creation timestamp of the python modules (in bundled Mac
builds) as follows, last built to first:

gui.so
core.so
analysis.so
utils.py
console.py
__init__.py

This makes sense why the gui.api overwrote the previous modules.
utils.py and console.py are just copied and can have their APIs built
with a direct command line sip call, after their copy, and from their
parent 'python/qgis/' directory.

If it was possible to slip in a name variable for analysis.so,
core.so, and gui.so during their sip build to produce
pyqgis_analysis.api, pyqgis_core.api, and pyqgis_gui.api,
respectively, that would solve the overwrite issue.

Post build you would end up with the following individual API files:

pyqgis_analysis.api
pyqgis_core.api
pyqgis_gui.api
pyqgis_console.api
pyqgis_utils.api

which I think you can just 'cat' those together and create pyqgis.api,
since there appears to be no metadata in the API files.

Referencing the built pyqgis.api you sent, it looks like everything
will work fine if users stick with the module import convention of:

from qgis import core, gui  (etc)

as the API lines started with 'qui.Qg..'.

I'm by no means a CMake wizard, but this seems fairly possible. Maybe
Phil Thompson could be consulted? Maybe the API files can be generated
using the .so files directly, after their creation, like regular
Python modules? (I saw no command line option for that.)

Thanks for the help, Gary.


Regards,

Larry Shaffer
Dakota Cartography
Black Hills, South Dakota