[Qgis-community-team] [QGIS-Developer] Codes in Cookbook and User manual : state of art

[Osahon Oduware]

https://www.docdroid.net/RTmOOr6/message-to-the-british-royal-family.pdf

On Wed, 18 Dec 2019, 10:09 DelazJ, <delazj at gmail.com> wrote:

> Hi,
> Good news Alessandro. Would be nice if that makes it. Thanks.
> Most of the information (other than the historic part, of course) are
> already in the readme and/or in the writing guidelines as far as I
> remember. Will double check when I find time.
>
> Regards,
> Harrissou
>
> Le mer. 18 déc. 2019 à 08:48, Alessandro Pasotti <apasotti at gmail.com> a
> écrit :
>
>> Thank you Harrissou,
>>
>> this is very valuable information, I think you should copy/paste it to
>> some README in the docs repo (if not yet there).
>>
>> I'd really like to make a deep revision and update of the cookbook and
>> put code snippets under automated testing, I'll ask the PSC if there are
>> any funds left for such activity.
>>
>> Cheers
>>
>>
>>
>> On Wed, Dec 18, 2019 at 7:30 AM DelazJ <delazj at gmail.com> wrote:
>>
>>> Hi all,
>>>
>>> During the last meeting for docs, there were some people asking whether
>>> and to which extent our documentation was linked to our API docs. While
>>> some answers have been given I'd hereby like to expand a bit on the subject.
>>>
>>> As you probably know, we rely on Sphinx to build our docs. And we also
>>> use two extensions of Sphinx to link to our code documentation (actually
>>> PyQGIS):
>>>
>>> 1. intersphinx [0] added by Alexandre Neto: connects user manual and
>>> cookbook with the pyQGIS documentation. Whenever we mention a class, it's
>>> possible to enable a URL that points to the class/function doc in pyQGIS
>>> website, in the corresponding release (ie for LTRs and master). Convenient
>>> for users, imho.
>>> Code is available at [1] and some examples at [2]. We have covered >90%
>>> (not scientific, but probably true!) of what needed to be and this works
>>> pretty well, as long as the pyQGIS doc builds successfully and
>>> classes/functions are still in the target QGIS version.
>>>
>>> 2. The other extension is doctest [3] added by Arnaud Morvan at La
>>> Coruna if I'm right: runs the target code snippets on QGIS and reports any
>>> error. This is mainly intended to get the cookbook examples fixed faster
>>> than manual trial, and less fragile. Basically, you add ".. testcode" at
>>> the beginning of a snippet and ".. testoutput" with expected output at the
>>> end and this code is tested at each build like if you were running it in
>>> QGIS. Instructions are at [4].
>>> While looking around for information to write this message, I realise
>>> that Victor Olaya also made a precious initial work of updates of the codes
>>> from 2 to 3 [5] automatically. But not on all the files as far as I could
>>> see. Maybe could we reuse his code?
>>> Today, we are far from the coverage we should have been imho, meaning
>>> that there still are a lot of codes that are outdated or can become
>>> outdated without noticing, because:
>>> - we need people to pick each
>>> - there isn't a way (or we don't know how) to test iface in the codes,
>>> resulting in many interface-related codes untestable.
>>>
>>> Hope that clarifies, and may those who were parts of this feel free to
>>> correct if I miss anything.
>>>
>>> Regards,
>>> Harrissou
>>>
>>> [0]
>>> http://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html
>>> [1]
>>> https://github.com/qgis/QGIS-Documentation/blob/master/source/conf.py#L113
>>> [2]
>>> https://docs.qgis.org/testing/en/docs/user_manual/processing/console.html#creating-scripts-and-running-them-from-the-toolbox
>>> [3] http://www.sphinx-doc.org/en/master/usage/extensions/doctest.html
>>> [4] https://github.com/qgis/QGIS-Documentation#testing-python-snippets
>>> [5]
>>> https://github.com/qgis/QGIS-Documentation/pull/3406#issuecomment-458462153
>>> _______________________________________________
>>> 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
>>
> _______________________________________________
> Qgis-community-team mailing list for organizing community resources such
> as documentation, translation etc..
> Qgis-community-team at lists.osgeo.org
> https://lists.osgeo.org/mailman/listinfo/qgis-community-team
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.osgeo.org/pipermail/qgis-community-team/attachments/20191225/01251688/attachment.html>