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

[DelazJ]

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
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.osgeo.org/pipermail/qgis-developer/attachments/20191218/26e71f51/attachment.html>