[Qgis-developer] automatic sip files generation

[Tim Sutton]

Hi

> On 30 Mar 2017, at 5:08 PM, Matthias Kuhn <matthias at opengis.ch> wrote:
> 
> Hi Denis,
> 
> Thanks a lot for finishing this.
> 
> I am really excited and expect less troubles on the sip front in the
> long-term.
> 
> Tim, actually the generated python code now includes python DocStrings,
> so it should be much easier to inspect an appropriate python
> documentation directly with `help(QgsVectorLayer)` etc.
> 
> And to automatically generate an up-to-date python documentation.

This is really great! I guess the next step would be to see if we can use autodoc to generate python documentation on the python libs. If that works it will go a long way towards bump starting the Python API work that Wes and Francisco were going to work on under a small QGIS funded project. The project never got out the starting gates because we could not come up with an elegant build system.

Might I suggest that we do our python documentation in a sphinx friendly way? So for example where you did:

@versionadded 3.0 in https://github.com/qgis/QGIS/pull/4318/files#diff-356d7cb762f7b9dfa4526f102450a9aaR41

it would become

..versionadded:: 3.0

See http://www.sphinx-doc.org/en/stable/markup/para.html

Since we are in green fields with python docstrings here it would be nice to have everything clean and neat and pythonic out the gate. Or are there some restrictions in the sippy annotations that require you to use a certain docstring style?

Regards

Tim

> 
> Cheers
> Matthias
> 
> On 03/30/2017 05:02 PM, Denis Rouzaud wrote:
>> 
>> 
>> Le jeu. 30 mars 2017 à 16:56, Tim Sutton <tim at kartoza.com <mailto:tim at kartoza.com>
>> <mailto:tim at kartoza.com <mailto:tim at kartoza.com>>> a écrit :
>> 
>>    Hi
>> 
>>>    On 30 Mar 2017, at 3:18 PM, Denis Rouzaud <denis.rouzaud at gmail.com <mailto:denis.rouzaud at gmail.com>
>>>    <mailto:denis.rouzaud at gmail.com <mailto:denis.rouzaud at gmail.com>>> wrote:
>>> 
>>>    Dear all,
>>> 
>>>    I'd like to raise the attention on a new workflow I just merged to
>>>    automatically generate SIP files using the header as source only.
>>> 
>>>    A PR is pending for the documentation, but you can read it here
>>>    https://github.com/3nids/QGIS-Documentation/blob/6e3a9fb6f98a2869aef27c01b7ab70eb0a4c7556/source/docs/developers_guide/codingstandards.rst#sip-bindings
>>>    (waiting to be merged).
>>> 
>>>    For the moment, only 3 files are generated (qgsattributes,
>>>    qgsfeature and qgsvectorlayer). One can starts adding new files to
>>>    the process by adapting their header and removing them from
>>>    python/auto_sip.blacklist.
>> 
>>    This is really great! A couple of questions:
>> 
>>    1) the blacklist implies that any new .h files added to the source
>>    tree will automatically have sip bindings generated unless you
>>    explicitly blacklist them?
>> 
>> 
>> As soon as you add the include in python/core/core.sip (or gui,
>> analysis), the SIP is considered as automatically generated from header
>> except if you blacklist it.
>> 
>> 
>>    2) are you thinking to maintain the sip files in Git still or remove
>>    the from revision in favour of having them as build time artifacts
>>    only? I ask this because I often direct people to use the sip files
>>    as a reference guide for the python API if they want to dig under
>>    the hood a bit more.
>> 
>> 
>> The goal is to remove the SIP files and have them created on build time.
>> But:
>> 1) I except a few errors in the script to arise (so better to have an
>> easy access to the SIP files)
>> 2) it needs to reach a significant point of ported headers.
>> 
>> So, in a somehow close or far future, yes they'll be removed from source
>> (hence no blacklist anymore only manual files such as core/conversions.sip).
>> 
>> 
>> _______________________________________________
>> Qgis-developer mailing list
>> Qgis-developer at lists.osgeo.org <mailto:Qgis-developer at lists.osgeo.org>
>> List info: https://lists.osgeo.org/mailman/listinfo/qgis-developer <https://lists.osgeo.org/mailman/listinfo/qgis-developer>
>> Unsubscribe: https://lists.osgeo.org/mailman/listinfo/qgis-developer <https://lists.osgeo.org/mailman/listinfo/qgis-developer>
>> 
> _______________________________________________
> Qgis-developer mailing list
> Qgis-developer at lists.osgeo.org <mailto:Qgis-developer at lists.osgeo.org>
> List info: https://lists.osgeo.org/mailman/listinfo/qgis-developer <https://lists.osgeo.org/mailman/listinfo/qgis-developer>
> Unsubscribe: https://lists.osgeo.org/mailman/listinfo/qgis-developer <https://lists.osgeo.org/mailman/listinfo/qgis-developer>
—










Tim Sutton

Co-founder: Kartoza
Project chair: QGIS.org

Visit http://kartoza.com <http://kartoza.com/> to find out about open source:

Desktop GIS programming services
Geospatial web development
GIS Training
Consulting Services

Skype: timlinux 
IRC: timlinux on #qgis at freenode.net

Kartoza is a merger between Linfiniti and Afrispatial

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.osgeo.org/pipermail/qgis-developer/attachments/20170330/c82e3d2e/attachment-0001.html>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: KartozaNewLogoThumbnail.jpg
Type: image/jpeg
Size: 6122 bytes
Desc: not available
URL: <http://lists.osgeo.org/pipermail/qgis-developer/attachments/20170330/c82e3d2e/attachment-0001.jpg>