[Qgis-developer] PyQGIS documentation (and SIP files)

[Alessandro Pasotti]

On Wed, Mar 8, 2017 at 9:34 AM, Nathan Woodrow <madmanwoo at gmail.com> wrote:

> I'm not sure we need the headers in the sip files to make a python docs
> API do we. That is the first thing to work out.
>

I don't know, all I know is that you can build API docs with doxygen using
sip files as a source: this is an ancient try that I did a few years ago
http://www.itopen.it/qgis/serverplugins/api/classQgsServerInterface.html

The result is far from ideal though, but maybe it could be refined.
There might be other ways to build the Python API docs, like using
introspection, but I'm not sure about how can we grab the documentation
from the C++ headers if we go that route.




>
> On Wed, 8 Mar 2017 6:23 pm Alessandro Pasotti <apasotti at gmail.com> wrote:
>
>> Hi,
>>
>> I think we still lack a up-to-date comprehensive documentation targeted
>> to Python QGIS developers and I would like to discuss the options that we
>> have to improve the current situation.
>>
>> As a Python QGIS developer, what I probably need is:
>> 1. Python API docs, possibly with examples
>> 2. Developer documentation about how to write PyQGIS plugins and
>> standalone applications
>> 3. Tutorials and examples
>> 4. Scaffolding
>>
>>
>> 2 and 3. the cookbook is doing a very good job, but it could probably be
>> improved and kept in sync with the API changes
>> 4. is perfectly covered by plugin builders
>> 1. this is were IMO we should do better: for most experienced QGIS
>> developers it's perfectly fine to look at the C++ API docs, but I think
>> that for Python developers that is not ideal
>>
>> There have been some efforts to build PyQGIS API documentation:
>> http://geoapis.sourcepole.com/qgispyapi/qgisinterface , maybe Sourcepole
>> colleagues could share their experience in building that pages.
>>
>> My main concern here is that we are slowly moving away from documenting
>> SIP files, I don't know if we can still build PyQGIS documentation without
>> documenting the SIP files but we should think carefully before taking a
>> move that will block us from using SIP files as a source for building the
>> docs.
>>
>>
>> What do you think about this?
>>
>>
>> --
>> Alessandro Pasotti
>> w3:   www.itopen.it
>> _______________________________________________
>> Qgis-developer mailing list
>> Qgis-developer at lists.osgeo.org
>> List info: https://lists.osgeo.org/mailman/listinfo/qgis-developer
>> Unsubscribe: https://lists.osgeo.org/mailman/listinfo/qgis-developer
>
>


-- 
Alessandro Pasotti
w3:   www.itopen.it
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.osgeo.org/pipermail/qgis-developer/attachments/20170308/01d356a1/attachment.html>