PyQgis Cookbook revision

classic Classic list List threaded Threaded
33 messages Options
12
Reply | Threaded
Open this post in threaded view
|

PyQgis Cookbook revision

Alessandro Pasotti-2
Hi,

I'd like like to make a deep revision and update of the cookbook and put code snippets under automated testing.

Are there any funds left for such activity?

--
Alessandro Pasotti
w3:   www.itopen.it

_______________________________________________
Qgis-psc mailing list
[hidden email]
https://lists.osgeo.org/mailman/listinfo/qgis-psc
Reply | Threaded
Open this post in threaded view
|

Re: PyQgis Cookbook revision

pcav
Hi Ale,
would this be suitable for a grant project?
Cheers.

Il 18/12/19 08:50, Alessandro Pasotti ha scritto:

> Hi,
>
> I'd like like to make a deep revision and update of the cookbook and put
> code snippets under automated testing.
>
> Are there any funds left for such activity?
>
> --
> Alessandro Pasotti
> w3:   www.itopen.it <http://www.itopen.it>
>
> _______________________________________________
> Qgis-psc mailing list
> [hidden email]
> https://lists.osgeo.org/mailman/listinfo/qgis-psc
>

--
Paolo Cavallini - www.faunalia.eu
QGIS.ORG Chair:
http://planet.qgis.org/planet/user/28/tag/qgis%20board/
_______________________________________________
Qgis-psc mailing list
[hidden email]
https://lists.osgeo.org/mailman/listinfo/qgis-psc
Reply | Threaded
Open this post in threaded view
|

Re: PyQgis Cookbook revision

Alessandro Pasotti-2


On Wed, Dec 18, 2019 at 8:54 AM Paolo Cavallini <[hidden email]> wrote:
Hi Ale,
would this be suitable for a grant project?


You tell me :)

I thought I would have time to do it now in the next few weeks, but if I will still have time later in the year I will apply for a grant.

Cheers

Cheers.

Il 18/12/19 08:50, Alessandro Pasotti ha scritto:
> Hi,
>
> I'd like like to make a deep revision and update of the cookbook and put
> code snippets under automated testing.
>
> Are there any funds left for such activity?
>
> --
> Alessandro Pasotti
> w3:   www.itopen.it <http://www.itopen.it>
>
> _______________________________________________
> Qgis-psc mailing list
> [hidden email]
> https://lists.osgeo.org/mailman/listinfo/qgis-psc
>

--
Paolo Cavallini - www.faunalia.eu
QGIS.ORG Chair:
http://planet.qgis.org/planet/user/28/tag/qgis%20board/
_______________________________________________
Qgis-psc mailing list
[hidden email]
https://lists.osgeo.org/mailman/listinfo/qgis-psc


--
Alessandro Pasotti
w3:   www.itopen.it

_______________________________________________
Qgis-psc mailing list
[hidden email]
https://lists.osgeo.org/mailman/listinfo/qgis-psc
Reply | Threaded
Open this post in threaded view
|

Re: PyQgis Cookbook revision

pcav
OK, if it's a quick thing then please submit a proposal and we'll vote
it ASAP.
Thanks.

Il 18/12/19 08:57, Alessandro Pasotti ha scritto:

>
>
> On Wed, Dec 18, 2019 at 8:54 AM Paolo Cavallini <[hidden email]
> <mailto:[hidden email]>> wrote:
>
>     Hi Ale,
>     would this be suitable for a grant project?
>
>
>
> You tell me :)
>
> I thought I would have time to do it now in the next few weeks, but if I
> will still have time later in the year I will apply for a grant.
>
> Cheers
>
>     Cheers.
>
>     Il 18/12/19 08:50, Alessandro Pasotti ha scritto:
>     > Hi,
>     >
>     > I'd like like to make a deep revision and update of the cookbook
>     and put
>     > code snippets under automated testing.
>     >
>     > Are there any funds left for such activity?
>     >
>     > --
>     > Alessandro Pasotti
>     > w3:   www.itopen.it <http://www.itopen.it> <http://www.itopen.it>
>     >
>     > _______________________________________________
>     > Qgis-psc mailing list
>     > [hidden email] <mailto:[hidden email]>
>     > https://lists.osgeo.org/mailman/listinfo/qgis-psc
>     >
>
>     --
>     Paolo Cavallini - www.faunalia.eu <http://www.faunalia.eu>
>     QGIS.ORG <http://QGIS.ORG> Chair:
>     http://planet.qgis.org/planet/user/28/tag/qgis%20board/
>     _______________________________________________
>     Qgis-psc mailing list
>     [hidden email] <mailto:[hidden email]>
>     https://lists.osgeo.org/mailman/listinfo/qgis-psc
>
>
>
> --
> Alessandro Pasotti
> w3:   www.itopen.it <http://www.itopen.it>

--
Paolo Cavallini - www.faunalia.eu
QGIS.ORG Chair:
http://planet.qgis.org/planet/user/28/tag/qgis%20board/
_______________________________________________
Qgis-psc mailing list
[hidden email]
https://lists.osgeo.org/mailman/listinfo/qgis-psc
Reply | Threaded
Open this post in threaded view
|

Re: PyQgis Cookbook revision

Alessandro Pasotti-2

On Wed, Dec 18, 2019 at 8:59 AM Paolo Cavallini <[hidden email]> wrote:
OK, if it's a quick thing then please submit a proposal and we'll vote
it ASAP.
Thanks.

I've done a quick research, the current cookbook situation appears to be:

- python code samples/snippets: 202
- python code samples/snippets currently tested: 53

So, I think that the plan would be to:
1. check all the cookbook text for 3.10 API changes and update it accordingly
2. put the 149 untested snippets under test

As far as point 1 is concerned the following files have the 'outofdate' directive:
 
./source/docs/pyqgis_developer_cookbook/server.rst
./source/docs/pyqgis_developer_cookbook/settings.rst
./source/docs/pyqgis_developer_cookbook/network_analysis.rst
./source/docs/pyqgis_developer_cookbook/canvas.rst
./source/docs/pyqgis_developer_cookbook/authentication.rst
./source/docs/pyqgis_developer_cookbook/plugins/ide_debugging.rst
./source/docs/pyqgis_developer_cookbook/plugins/pluginlayer.rst
./source/docs/pyqgis_developer_cookbook/plugins/releasing.rst
./source/docs/pyqgis_developer_cookbook/raster.rst

this of course doesn't mean that all others are necessarily uptodate,
but we can assume that they require less work to be updated.

It's a bit difficult to estimate the exact amount of work required to achieve
both tasks, especially because some code samples will require quite a lot
of setup and data in order to run in the automatic tests.

However, I think the most efficient way to proceed is to work on both
tasks simultaneously: while checking the code samples it will be easier
to also apply corrections to the text.

So, what I would like to propose is to start with 5 days of work and see where we
can get with that, there are probably some APIs that haven't changed much
between releases (authentication is an example).

Btw, when looking at this, I've added this small improvement: https://github.com/qgis/QGIS-Documentation/pull/4651

Cheers



Il 18/12/19 08:57, Alessandro Pasotti ha scritto:
>
>
> On Wed, Dec 18, 2019 at 8:54 AM Paolo Cavallini <[hidden email]
> <mailto:[hidden email]>> wrote:
>
>     Hi Ale,
>     would this be suitable for a grant project?
>
>
>
> You tell me :)
>
> I thought I would have time to do it now in the next few weeks, but if I
> will still have time later in the year I will apply for a grant.
>
> Cheers
>
>     Cheers.
>
>     Il 18/12/19 08:50, Alessandro Pasotti ha scritto:
>     > Hi,
>     >
>     > I'd like like to make a deep revision and update of the cookbook
>     and put
>     > code snippets under automated testing.
>     >
>     > Are there any funds left for such activity?
>     >
>     > --
>     > Alessandro Pasotti
>     > w3:   www.itopen.it <http://www.itopen.it> <http://www.itopen.it>
>     >
>     > _______________________________________________
>     > Qgis-psc mailing list
>     > [hidden email] <mailto:[hidden email]>
>     > https://lists.osgeo.org/mailman/listinfo/qgis-psc
>     >
>
>     --
>     Paolo Cavallini - www.faunalia.eu <http://www.faunalia.eu>
>     QGIS.ORG <http://QGIS.ORG> Chair:
>     http://planet.qgis.org/planet/user/28/tag/qgis%20board/
>     _______________________________________________
>     Qgis-psc mailing list
>     [hidden email] <mailto:[hidden email]>
>     https://lists.osgeo.org/mailman/listinfo/qgis-psc
>
>
>
> --
> Alessandro Pasotti
> w3:   www.itopen.it <http://www.itopen.it>

--
Paolo Cavallini - www.faunalia.eu
QGIS.ORG Chair:
http://planet.qgis.org/planet/user/28/tag/qgis%20board/


--
Alessandro Pasotti
w3:   www.itopen.it

_______________________________________________
Qgis-psc mailing list
[hidden email]
https://lists.osgeo.org/mailman/listinfo/qgis-psc
Reply | Threaded
Open this post in threaded view
|

Re: PyQgis Cookbook revision

Marco Bernasocchi-2

Hi Alessandro, thanks a lot for the analysis, as I already mentioned in the docs meeting I think the py cookbook is very important and needs lots of love.

I like your suggestion and I'd be in favour of doing it.

cheers

Marco

On 19.12.19 15:37, Alessandro Pasotti wrote:

On Wed, Dec 18, 2019 at 8:59 AM Paolo Cavallini <[hidden email]> wrote:
OK, if it's a quick thing then please submit a proposal and we'll vote
it ASAP.
Thanks.

I've done a quick research, the current cookbook situation appears to be:

- python code samples/snippets: 202
- python code samples/snippets currently tested: 53

So, I think that the plan would be to:
1. check all the cookbook text for 3.10 API changes and update it accordingly
2. put the 149 untested snippets under test

As far as point 1 is concerned the following files have the 'outofdate' directive:
 
./source/docs/pyqgis_developer_cookbook/server.rst
./source/docs/pyqgis_developer_cookbook/settings.rst
./source/docs/pyqgis_developer_cookbook/network_analysis.rst
./source/docs/pyqgis_developer_cookbook/canvas.rst
./source/docs/pyqgis_developer_cookbook/authentication.rst
./source/docs/pyqgis_developer_cookbook/plugins/ide_debugging.rst
./source/docs/pyqgis_developer_cookbook/plugins/pluginlayer.rst
./source/docs/pyqgis_developer_cookbook/plugins/releasing.rst
./source/docs/pyqgis_developer_cookbook/raster.rst

this of course doesn't mean that all others are necessarily uptodate,
but we can assume that they require less work to be updated.

It's a bit difficult to estimate the exact amount of work required to achieve
both tasks, especially because some code samples will require quite a lot
of setup and data in order to run in the automatic tests.

However, I think the most efficient way to proceed is to work on both
tasks simultaneously: while checking the code samples it will be easier
to also apply corrections to the text.

So, what I would like to propose is to start with 5 days of work and see where we
can get with that, there are probably some APIs that haven't changed much
between releases (authentication is an example).

Btw, when looking at this, I've added this small improvement: https://github.com/qgis/QGIS-Documentation/pull/4651

Cheers



Il 18/12/19 08:57, Alessandro Pasotti ha scritto:
>
>
> On Wed, Dec 18, 2019 at 8:54 AM Paolo Cavallini <[hidden email]
> <mailto:[hidden email]>> wrote:
>
>     Hi Ale,
>     would this be suitable for a grant project?
>
>
>
> You tell me :)
>
> I thought I would have time to do it now in the next few weeks, but if I
> will still have time later in the year I will apply for a grant.
>
> Cheers
>
>     Cheers.
>
>     Il 18/12/19 08:50, Alessandro Pasotti ha scritto:
>     > Hi,
>     >
>     > I'd like like to make a deep revision and update of the cookbook
>     and put
>     > code snippets under automated testing.
>     >
>     > Are there any funds left for such activity?
>     >
>     > --
>     > Alessandro Pasotti
>     > w3:   www.itopen.it <http://www.itopen.it> <http://www.itopen.it>
>     >
>     > _______________________________________________
>     > Qgis-psc mailing list
>     > [hidden email] <mailto:[hidden email]>
>     > https://lists.osgeo.org/mailman/listinfo/qgis-psc
>     >
>
>     --
>     Paolo Cavallini - www.faunalia.eu <http://www.faunalia.eu>
>     QGIS.ORG <http://QGIS.ORG> Chair:
>     http://planet.qgis.org/planet/user/28/tag/qgis%20board/
>     _______________________________________________
>     Qgis-psc mailing list
>     [hidden email] <mailto:[hidden email]>
>     https://lists.osgeo.org/mailman/listinfo/qgis-psc
>
>
>
> --
> Alessandro Pasotti
> w3:   www.itopen.it <http://www.itopen.it>

--
Paolo Cavallini - www.faunalia.eu
QGIS.ORG Chair:
http://planet.qgis.org/planet/user/28/tag/qgis%20board/


--
Alessandro Pasotti
w3:   www.itopen.it

_______________________________________________
Qgis-psc mailing list
[hidden email]
https://lists.osgeo.org/mailman/listinfo/qgis-psc
-- 
Marco Bernasocchi

QGIS.org Co-chair
http://berna.io

_______________________________________________
Qgis-psc mailing list
[hidden email]
https://lists.osgeo.org/mailman/listinfo/qgis-psc
Reply | Threaded
Open this post in threaded view
|

Re: PyQgis Cookbook revision

3nids
Hi all,

I was wondering if the cookbook could be integrated with the API docs website.
It would be nice, we could test everything there (it uses the QGIS docker images), and it would have a single coherente endpoint.

Ale, feel free to get in touch :)

Denis

Le jeu. 19 déc. 2019 à 16:04, Marco Bernasocchi <[hidden email]> a écrit :

Hi Alessandro, thanks a lot for the analysis, as I already mentioned in the docs meeting I think the py cookbook is very important and needs lots of love.

I like your suggestion and I'd be in favour of doing it.

cheers

Marco

On 19.12.19 15:37, Alessandro Pasotti wrote:

On Wed, Dec 18, 2019 at 8:59 AM Paolo Cavallini <[hidden email]> wrote:
OK, if it's a quick thing then please submit a proposal and we'll vote
it ASAP.
Thanks.

I've done a quick research, the current cookbook situation appears to be:

- python code samples/snippets: 202
- python code samples/snippets currently tested: 53

So, I think that the plan would be to:
1. check all the cookbook text for 3.10 API changes and update it accordingly
2. put the 149 untested snippets under test

As far as point 1 is concerned the following files have the 'outofdate' directive:
 
./source/docs/pyqgis_developer_cookbook/server.rst
./source/docs/pyqgis_developer_cookbook/settings.rst
./source/docs/pyqgis_developer_cookbook/network_analysis.rst
./source/docs/pyqgis_developer_cookbook/canvas.rst
./source/docs/pyqgis_developer_cookbook/authentication.rst
./source/docs/pyqgis_developer_cookbook/plugins/ide_debugging.rst
./source/docs/pyqgis_developer_cookbook/plugins/pluginlayer.rst
./source/docs/pyqgis_developer_cookbook/plugins/releasing.rst
./source/docs/pyqgis_developer_cookbook/raster.rst

this of course doesn't mean that all others are necessarily uptodate,
but we can assume that they require less work to be updated.

It's a bit difficult to estimate the exact amount of work required to achieve
both tasks, especially because some code samples will require quite a lot
of setup and data in order to run in the automatic tests.

However, I think the most efficient way to proceed is to work on both
tasks simultaneously: while checking the code samples it will be easier
to also apply corrections to the text.

So, what I would like to propose is to start with 5 days of work and see where we
can get with that, there are probably some APIs that haven't changed much
between releases (authentication is an example).

Btw, when looking at this, I've added this small improvement: https://github.com/qgis/QGIS-Documentation/pull/4651

Cheers



Il 18/12/19 08:57, Alessandro Pasotti ha scritto:
>
>
> On Wed, Dec 18, 2019 at 8:54 AM Paolo Cavallini <[hidden email]
> <mailto:[hidden email]>> wrote:
>
>     Hi Ale,
>     would this be suitable for a grant project?
>
>
>
> You tell me :)
>
> I thought I would have time to do it now in the next few weeks, but if I
> will still have time later in the year I will apply for a grant.
>
> Cheers
>
>     Cheers.
>
>     Il 18/12/19 08:50, Alessandro Pasotti ha scritto:
>     > Hi,
>     >
>     > I'd like like to make a deep revision and update of the cookbook
>     and put
>     > code snippets under automated testing.
>     >
>     > Are there any funds left for such activity?
>     >
>     > --
>     > Alessandro Pasotti
>     > w3:   www.itopen.it <http://www.itopen.it> <http://www.itopen.it>
>     >
>     > _______________________________________________
>     > Qgis-psc mailing list
>     > [hidden email] <mailto:[hidden email]>
>     > https://lists.osgeo.org/mailman/listinfo/qgis-psc
>     >
>
>     --
>     Paolo Cavallini - www.faunalia.eu <http://www.faunalia.eu>
>     QGIS.ORG <http://QGIS.ORG> Chair:
>     http://planet.qgis.org/planet/user/28/tag/qgis%20board/
>     _______________________________________________
>     Qgis-psc mailing list
>     [hidden email] <mailto:[hidden email]>
>     https://lists.osgeo.org/mailman/listinfo/qgis-psc
>
>
>
> --
> Alessandro Pasotti
> w3:   www.itopen.it <http://www.itopen.it>

--
Paolo Cavallini - www.faunalia.eu
QGIS.ORG Chair:
http://planet.qgis.org/planet/user/28/tag/qgis%20board/


--
Alessandro Pasotti
w3:   www.itopen.it

_______________________________________________
Qgis-psc mailing list
[hidden email]
https://lists.osgeo.org/mailman/listinfo/qgis-psc
-- 
Marco Bernasocchi

QGIS.org Co-chair
http://berna.io
_______________________________________________
Qgis-psc mailing list
[hidden email]
https://lists.osgeo.org/mailman/listinfo/qgis-psc

_______________________________________________
Qgis-psc mailing list
[hidden email]
https://lists.osgeo.org/mailman/listinfo/qgis-psc
Reply | Threaded
Open this post in threaded view
|

Re: PyQgis Cookbook revision

Alessandro Pasotti-2


On Thu, Dec 19, 2019 at 4:41 PM Denis Rouzaud <[hidden email]> wrote:
Hi all,

I was wondering if the cookbook could be integrated with the API docs website.
It would be nice, we could test everything there (it uses the QGIS docker images), and it would have a single coherente endpoint.

Ale, feel free to get in touch :)

Denis

Hi Denis,

Do you you mean adding the cookbook directly in the C++ class headers? Like https://github.com/qgis/QGIS/blob/master/src/server/qgsserverogcapi.h#L33 ?

This is what QT does, right?

If that's the case, I've thought about it and there are certainly some advantages: the most important one would probably be a unique source for code, API docs, PyQgis API docs and PyQgis recipes (the cookbook).
I'm not against it, but I'm not really sure it's the best option: I see the cookbook more like a "book", where there might be more space for longer paragraphs, pictures etc. and where the content can be organized independently from the Qgs* classes structure.

There are also sections in the cookbook that span across classes (the snippets mainly) or that do not really map to a single Qgs class.

In any event, the cookbook also uses a QGIS docker image for the python code tests (qgis/qgis:latest).

But maybe I totally misunderstood your proposal and you are just talking about moving the current cookbook content into another repo or suck it up when building PyQGIS API docs.

Cheers


Le jeu. 19 déc. 2019 à 16:04, Marco Bernasocchi <[hidden email]> a écrit :

Hi Alessandro, thanks a lot for the analysis, as I already mentioned in the docs meeting I think the py cookbook is very important and needs lots of love.

I like your suggestion and I'd be in favour of doing it.

cheers

Marco

On 19.12.19 15:37, Alessandro Pasotti wrote:

On Wed, Dec 18, 2019 at 8:59 AM Paolo Cavallini <[hidden email]> wrote:
OK, if it's a quick thing then please submit a proposal and we'll vote
it ASAP.
Thanks.

I've done a quick research, the current cookbook situation appears to be:

- python code samples/snippets: 202
- python code samples/snippets currently tested: 53

So, I think that the plan would be to:
1. check all the cookbook text for 3.10 API changes and update it accordingly
2. put the 149 untested snippets under test

As far as point 1 is concerned the following files have the 'outofdate' directive:
 
./source/docs/pyqgis_developer_cookbook/server.rst
./source/docs/pyqgis_developer_cookbook/settings.rst
./source/docs/pyqgis_developer_cookbook/network_analysis.rst
./source/docs/pyqgis_developer_cookbook/canvas.rst
./source/docs/pyqgis_developer_cookbook/authentication.rst
./source/docs/pyqgis_developer_cookbook/plugins/ide_debugging.rst
./source/docs/pyqgis_developer_cookbook/plugins/pluginlayer.rst
./source/docs/pyqgis_developer_cookbook/plugins/releasing.rst
./source/docs/pyqgis_developer_cookbook/raster.rst

this of course doesn't mean that all others are necessarily uptodate,
but we can assume that they require less work to be updated.

It's a bit difficult to estimate the exact amount of work required to achieve
both tasks, especially because some code samples will require quite a lot
of setup and data in order to run in the automatic tests.

However, I think the most efficient way to proceed is to work on both
tasks simultaneously: while checking the code samples it will be easier
to also apply corrections to the text.

So, what I would like to propose is to start with 5 days of work and see where we
can get with that, there are probably some APIs that haven't changed much
between releases (authentication is an example).

Btw, when looking at this, I've added this small improvement: https://github.com/qgis/QGIS-Documentation/pull/4651

Cheers



Il 18/12/19 08:57, Alessandro Pasotti ha scritto:
>
>
> On Wed, Dec 18, 2019 at 8:54 AM Paolo Cavallini <[hidden email]
> <mailto:[hidden email]>> wrote:
>
>     Hi Ale,
>     would this be suitable for a grant project?
>
>
>
> You tell me :)
>
> I thought I would have time to do it now in the next few weeks, but if I
> will still have time later in the year I will apply for a grant.
>
> Cheers
>
>     Cheers.
>
>     Il 18/12/19 08:50, Alessandro Pasotti ha scritto:
>     > Hi,
>     >
>     > I'd like like to make a deep revision and update of the cookbook
>     and put
>     > code snippets under automated testing.
>     >
>     > Are there any funds left for such activity?
>     >
>     > --
>     > Alessandro Pasotti
>     > w3:   www.itopen.it <http://www.itopen.it> <http://www.itopen.it>
>     >
>     > _______________________________________________
>     > Qgis-psc mailing list
>     > [hidden email] <mailto:[hidden email]>
>     > https://lists.osgeo.org/mailman/listinfo/qgis-psc
>     >
>
>     --
>     Paolo Cavallini - www.faunalia.eu <http://www.faunalia.eu>
>     QGIS.ORG <http://QGIS.ORG> Chair:
>     http://planet.qgis.org/planet/user/28/tag/qgis%20board/
>     _______________________________________________
>     Qgis-psc mailing list
>     [hidden email] <mailto:[hidden email]>
>     https://lists.osgeo.org/mailman/listinfo/qgis-psc
>
>
>
> --
> Alessandro Pasotti
> w3:   www.itopen.it <http://www.itopen.it>

--
Paolo Cavallini - www.faunalia.eu
QGIS.ORG Chair:
http://planet.qgis.org/planet/user/28/tag/qgis%20board/


--
Alessandro Pasotti
w3:   www.itopen.it

_______________________________________________
Qgis-psc mailing list
[hidden email]
https://lists.osgeo.org/mailman/listinfo/qgis-psc
-- 
Marco Bernasocchi

QGIS.org Co-chair
http://berna.io
_______________________________________________
Qgis-psc mailing list
[hidden email]
https://lists.osgeo.org/mailman/listinfo/qgis-psc


--
Alessandro Pasotti
w3:   www.itopen.it

_______________________________________________
Qgis-psc mailing list
[hidden email]
https://lists.osgeo.org/mailman/listinfo/qgis-psc
Reply | Threaded
Open this post in threaded view
|

Re: PyQgis Cookbook revision

3nids
Hi Ale,

Sorry for not being clear.


Le jeu. 19 déc. 2019 à 16:59, Alessandro Pasotti <[hidden email]> a écrit :


On Thu, Dec 19, 2019 at 4:41 PM Denis Rouzaud <[hidden email]> wrote:
Hi all,

I was wondering if the cookbook could be integrated with the API docs website.
It would be nice, we could test everything there (it uses the QGIS docker images), and it would have a single coherente endpoint.

Ale, feel free to get in touch :)

Denis

Hi Denis,

Do you you mean adding the cookbook directly in the C++ class headers? Like https://github.com/qgis/QGIS/blob/master/src/server/qgsserverogcapi.h#L33 ?

This is what QT does, right?

If that's the case, I've thought about it and there are certainly some advantages: the most important one would probably be a unique source for code, API docs, PyQgis API docs and PyQgis recipes (the cookbook).
I'm not against it, but I'm not really sure it's the best option: I see the cookbook more like a "book", where there might be more space for longer paragraphs, pictures etc. and where the content can be organized independently from the Qgs* classes structure.

There are also sections in the cookbook that span across classes (the snippets mainly) or that do not really map to a single Qgs class.


Yeah, I'm totally with you here. While it sounds like a clever idea at first, you hit so many issues like this which will just make the work much harder at the end.

In any event, the cookbook also uses a QGIS docker image for the python code tests (qgis/qgis:latest).

But maybe I totally misunderstood your proposal and you are just talking about moving the current cookbook content into another repo or suck it up when building PyQGIS API docs.


Yes, I have 2 points:
* Build the API docs and the cookbook in the same job (but I don't care that much if not)
* Bring the cookbook under the same website as qgis.org/pyqgis so we have a single entry for all python related stuff.

Cheers
Denis


_______________________________________________
Qgis-psc mailing list
[hidden email]
https://lists.osgeo.org/mailman/listinfo/qgis-psc
Reply | Threaded
Open this post in threaded view
|

Re: PyQgis Cookbook revision

Tim Sutton-6
Hi All

Or put differently, I think the suggestion is to make the cookbook different section of the Python API docs sphinx project so that they are built and managed as one job.

Regards

Tim

On 20 Dec 2019, at 10:26, Denis Rouzaud <[hidden email]> wrote:

Hi Ale,

Sorry for not being clear.


Le jeu. 19 déc. 2019 à 16:59, Alessandro Pasotti <[hidden email]> a écrit :


On Thu, Dec 19, 2019 at 4:41 PM Denis Rouzaud <[hidden email]> wrote:
Hi all,

I was wondering if the cookbook could be integrated with the API docs website.
It would be nice, we could test everything there (it uses the QGIS docker images), and it would have a single coherente endpoint.

Ale, feel free to get in touch :)

Denis

Hi Denis,

Do you you mean adding the cookbook directly in the C++ class headers? Like https://github.com/qgis/QGIS/blob/master/src/server/qgsserverogcapi.h#L33 ?

This is what QT does, right?

If that's the case, I've thought about it and there are certainly some advantages: the most important one would probably be a unique source for code, API docs, PyQgis API docs and PyQgis recipes (the cookbook). 
I'm not against it, but I'm not really sure it's the best option: I see the cookbook more like a "book", where there might be more space for longer paragraphs, pictures etc. and where the content can be organized independently from the Qgs* classes structure. 

There are also sections in the cookbook that span across classes (the snippets mainly) or that do not really map to a single Qgs class.


Yeah, I'm totally with you here. While it sounds like a clever idea at first, you hit so many issues like this which will just make the work much harder at the end.

In any event, the cookbook also uses a QGIS docker image for the python code tests (qgis/qgis:latest).

But maybe I totally misunderstood your proposal and you are just talking about moving the current cookbook content into another repo or suck it up when building PyQGIS API docs.


Yes, I have 2 points:
* Build the API docs and the cookbook in the same job (but I don't care that much if not)
* Bring the cookbook under the same website as qgis.org/pyqgis so we have a single entry for all python related stuff.

Cheers
Denis

_______________________________________________
Qgis-psc mailing list
[hidden email]
https://lists.osgeo.org/mailman/listinfo/qgis-psc









Tim Sutton

Co-founder: Kartoza
Ex Project chair: QGIS.org

Visit 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

I'd love to connect. Here's my calendar link to make finding time easy.


_______________________________________________
Qgis-psc mailing list
[hidden email]
https://lists.osgeo.org/mailman/listinfo/qgis-psc
Reply | Threaded
Open this post in threaded view
|

Re: PyQgis Cookbook revision

Alessandro Pasotti-2
In reply to this post by 3nids


On Fri, Dec 20, 2019 at 11:26 AM Denis Rouzaud <[hidden email]> wrote:
Hi Ale,

Sorry for not being clear.


Le jeu. 19 déc. 2019 à 16:59, Alessandro Pasotti <[hidden email]> a écrit :


On Thu, Dec 19, 2019 at 4:41 PM Denis Rouzaud <[hidden email]> wrote:
Hi all,

I was wondering if the cookbook could be integrated with the API docs website.
It would be nice, we could test everything there (it uses the QGIS docker images), and it would have a single coherente endpoint.

Ale, feel free to get in touch :)

Denis

Hi Denis,

Do you you mean adding the cookbook directly in the C++ class headers? Like https://github.com/qgis/QGIS/blob/master/src/server/qgsserverogcapi.h#L33 ?

This is what QT does, right?

If that's the case, I've thought about it and there are certainly some advantages: the most important one would probably be a unique source for code, API docs, PyQgis API docs and PyQgis recipes (the cookbook).
I'm not against it, but I'm not really sure it's the best option: I see the cookbook more like a "book", where there might be more space for longer paragraphs, pictures etc. and where the content can be organized independently from the Qgs* classes structure.

There are also sections in the cookbook that span across classes (the snippets mainly) or that do not really map to a single Qgs class.


Yeah, I'm totally with you here. While it sounds like a clever idea at first, you hit so many issues like this which will just make the work much harder at the end.

In any event, the cookbook also uses a QGIS docker image for the python code tests (qgis/qgis:latest).

But maybe I totally misunderstood your proposal and you are just talking about moving the current cookbook content into another repo or suck it up when building PyQGIS API docs.


Yes, I have 2 points:
* Build the API docs and the cookbook in the same job (but I don't care that much if not)
* Bring the cookbook under the same website as qgis.org/pyqgis so we have a single entry for all python related stuff.

Cheers
Denis


Hi Denis,

thank you for the clarification, I don't have a strong opinion here, if I'm not wrong we currently have the following developer-oriented entry points:

- C++ API website
- Python API website
- Documentation website
  - developers guide (C++ oriented)
  - python cookbook (Python oriented)

(One bad thing is that they have complete different look and feel, but that's another story)

I'm not talking about the technical aspects now (building and testing) but from a user perspective, I think that what we should ideally achieve is something like:

- Documentation website
   - developers docs
        - generic material about PRs, code of conduit etc.
        - C++ developers guide
            - link to the C++ API
        - Python developers guide (the cookbook)
           - link to Python API

Whether the whole Python developers guide (cookbook + API) is an external link or not is probably not so important, except maybe for browsability from the main website and search capabilities from the main website.

Both the Python part and the C++ part are actually a mix of three separate topics:
- core development (C++ and core Python plugins and processing core algs)
- independent plugins (both C++ even if they are not very welcome lately and Python).
- standalone applications

In any event, if I get this right, moving the cookbook to a different sphinx project doesn't change much about the cookbook revision work I'm proposing to do, we can probably just move the doctest target into the python API project.

But I wonder if moving the cookbook out of the documentation doesn't create a problem with translations, I didn't check if there are any for the cookbook.

I think we should bring the documentation team into the discussion, is there a better place than this list where they have a better chance to get involved?

Cheers

--
Alessandro Pasotti
w3:   www.itopen.it

_______________________________________________
Qgis-psc mailing list
[hidden email]
https://lists.osgeo.org/mailman/listinfo/qgis-psc
Reply | Threaded
Open this post in threaded view
|

Re: PyQgis Cookbook revision

DelazJ
Hi all,

Quick points

Le ven. 20 déc. 2019 à 11:54, Alessandro Pasotti <[hidden email]> a écrit :

[...]

Whether the whole Python developers guide (cookbook + API) is an external link or not is probably not so important, except maybe for browsability from the main website and search capabilities from the main website.

The intersphinx  extension helps to reach Python API documentation from within the Cookbook or the User manual. The reverse is not (yet?) true and I don't know whether it's easy to do.

Both the Python part and the C++ part are actually a mix of three separate topics:
- core development (C++ and core Python plugins and processing core algs)
- independent plugins (both C++ even if they are not very welcome lately and Python).
- standalone applications

In any event, if I get this right, moving the cookbook to a different sphinx project doesn't change much about the cookbook revision work I'm proposing to do, we can probably just move the doctest target into the python API project.

But I wonder if moving the cookbook out of the documentation doesn't create a problem with translations, I didn't check if there are any for the cookbook.

Every document under qgis/QGIS-Documentation repository is currently translated.

Regards,
Harrissou

I think we should bring the documentation team into the discussion, is there a better place than this list where they have a better chance to get involved?

Cheers

--
Alessandro Pasotti
w3:   www.itopen.it
_______________________________________________
Qgis-psc mailing list
[hidden email]
https://lists.osgeo.org/mailman/listinfo/qgis-psc

_______________________________________________
Qgis-psc mailing list
[hidden email]
https://lists.osgeo.org/mailman/listinfo/qgis-psc
Reply | Threaded
Open this post in threaded view
|

Re: PyQgis Cookbook revision

Alessandro Pasotti-2


On Fri, Dec 20, 2019 at 12:22 PM DelazJ <[hidden email]> wrote:
Hi all,

Quick points
Le ven. 20 déc. 2019 à 11:54, Alessandro Pasotti <[hidden email]> a écrit :

[...]

Whether the whole Python developers guide (cookbook + API) is an external link or not is probably not so important, except maybe for browsability from the main website and search capabilities from the main website.

The intersphinx  extension helps to reach Python API documentation from within the Cookbook or the User manual. The reverse is not (yet?) true and I don't know whether it's easy to do.

Both the Python part and the C++ part are actually a mix of three separate topics:
- core development (C++ and core Python plugins and processing core algs)
- independent plugins (both C++ even if they are not very welcome lately and Python).
- standalone applications

In any event, if I get this right, moving the cookbook to a different sphinx project doesn't change much about the cookbook revision work I'm proposing to do, we can probably just move the doctest target into the python API project.

But I wonder if moving the cookbook out of the documentation doesn't create a problem with translations, I didn't check if there are any for the cookbook.

Every document under qgis/QGIS-Documentation repository is currently translated.


Hm, so I guess this is a blocker, right?

[hidden email]  given that the system to run CI tests on the Python code embedded in the cookbook is already in place, what are the technical advantages of moving the cookbook into the Python API sphinx project?

 

Regards,
Harrissou

I think we should bring the documentation team into the discussion, is there a better place than this list where they have a better chance to get involved?

Cheers

--
Alessandro Pasotti
w3:   www.itopen.it
_______________________________________________
Qgis-psc mailing list
[hidden email]
https://lists.osgeo.org/mailman/listinfo/qgis-psc


--
Alessandro Pasotti
w3:   www.itopen.it

_______________________________________________
Qgis-psc mailing list
[hidden email]
https://lists.osgeo.org/mailman/listinfo/qgis-psc
Reply | Threaded
Open this post in threaded view
|

Re: PyQgis Cookbook revision

Alexandre Neto
In the docs meeting we have talked about splitting/removing the python cookbook from the User manual (the same for other sections).

The advantages would be:

- We can release each document in separate
- We can break one of the docs without breaking the others
- we can have the cookbook more developers-oriented (even in the way it's written)

The disadvantages would be:
- We would need to set intersphinx in both projects to allow keep cross linking between them
- we would need to duplicate our sphinx project structure, and maintain it (themes, makefiles, CI, etc...)
- If we want to go with translation, we would need to set other transifex projects (at the meeting we kinda talked about the real need for translation for the cookbook, quickly browsing excelpt for spanish and french, most of other languages don't have it translated)

But anyway, like Alessandro said, the work that needs to be done, can be performed in any of the repositories.

Alexandre Neto

On Fri, Dec 20, 2019 at 11:29 AM Alessandro Pasotti <[hidden email]> wrote:


On Fri, Dec 20, 2019 at 12:22 PM DelazJ <[hidden email]> wrote:
Hi all,

Quick points
Le ven. 20 déc. 2019 à 11:54, Alessandro Pasotti <[hidden email]> a écrit :

[...]

Whether the whole Python developers guide (cookbook + API) is an external link or not is probably not so important, except maybe for browsability from the main website and search capabilities from the main website.

The intersphinx  extension helps to reach Python API documentation from within the Cookbook or the User manual. The reverse is not (yet?) true and I don't know whether it's easy to do.

Both the Python part and the C++ part are actually a mix of three separate topics:
- core development (C++ and core Python plugins and processing core algs)
- independent plugins (both C++ even if they are not very welcome lately and Python).
- standalone applications

In any event, if I get this right, moving the cookbook to a different sphinx project doesn't change much about the cookbook revision work I'm proposing to do, we can probably just move the doctest target into the python API project.

But I wonder if moving the cookbook out of the documentation doesn't create a problem with translations, I didn't check if there are any for the cookbook.

Every document under qgis/QGIS-Documentation repository is currently translated.


Hm, so I guess this is a blocker, right?

[hidden email]  given that the system to run CI tests on the Python code embedded in the cookbook is already in place, what are the technical advantages of moving the cookbook into the Python API sphinx project?

 

Regards,
Harrissou

I think we should bring the documentation team into the discussion, is there a better place than this list where they have a better chance to get involved?

Cheers

--
Alessandro Pasotti
w3:   www.itopen.it
_______________________________________________
Qgis-psc mailing list
[hidden email]
https://lists.osgeo.org/mailman/listinfo/qgis-psc


--
Alessandro Pasotti
w3:   www.itopen.it
_______________________________________________
Qgis-psc mailing list
[hidden email]
https://lists.osgeo.org/mailman/listinfo/qgis-psc

_______________________________________________
Qgis-psc mailing list
[hidden email]
https://lists.osgeo.org/mailman/listinfo/qgis-psc
Reply | Threaded
Open this post in threaded view
|

Re: PyQgis Cookbook revision

DelazJ
Hi PSC,

I didn't want to ask during the feature freeze since I know Alessandro would anyway be busy with coding but now that it's over it would be nice to get a decision from the PSC whether the update of the cookbook as he proposed (http://osgeo-org.1560.x6.nabble.com/PyQgis-Cookbook-revision-tp5425519p5425665.html) could be done.
Fwiw, I don't think that we should postpone that to grant proposal given that the docs might have their own budget and this fix should not be in competition with other areas of QGIS.

Greetings
Harrissou

Le ven. 20 déc. 2019 à 15:41, Alexandre Neto <[hidden email]> a écrit :
In the docs meeting we have talked about splitting/removing the python cookbook from the User manual (the same for other sections).

The advantages would be:

- We can release each document in separate
- We can break one of the docs without breaking the others
- we can have the cookbook more developers-oriented (even in the way it's written)

The disadvantages would be:
- We would need to set intersphinx in both projects to allow keep cross linking between them
- we would need to duplicate our sphinx project structure, and maintain it (themes, makefiles, CI, etc...)
- If we want to go with translation, we would need to set other transifex projects (at the meeting we kinda talked about the real need for translation for the cookbook, quickly browsing excelpt for spanish and french, most of other languages don't have it translated)

But anyway, like Alessandro said, the work that needs to be done, can be performed in any of the repositories.

Alexandre Neto

On Fri, Dec 20, 2019 at 11:29 AM Alessandro Pasotti <[hidden email]> wrote:


On Fri, Dec 20, 2019 at 12:22 PM DelazJ <[hidden email]> wrote:
Hi all,

Quick points
Le ven. 20 déc. 2019 à 11:54, Alessandro Pasotti <[hidden email]> a écrit :

[...]

Whether the whole Python developers guide (cookbook + API) is an external link or not is probably not so important, except maybe for browsability from the main website and search capabilities from the main website.

The intersphinx  extension helps to reach Python API documentation from within the Cookbook or the User manual. The reverse is not (yet?) true and I don't know whether it's easy to do.

Both the Python part and the C++ part are actually a mix of three separate topics:
- core development (C++ and core Python plugins and processing core algs)
- independent plugins (both C++ even if they are not very welcome lately and Python).
- standalone applications

In any event, if I get this right, moving the cookbook to a different sphinx project doesn't change much about the cookbook revision work I'm proposing to do, we can probably just move the doctest target into the python API project.

But I wonder if moving the cookbook out of the documentation doesn't create a problem with translations, I didn't check if there are any for the cookbook.

Every document under qgis/QGIS-Documentation repository is currently translated.


Hm, so I guess this is a blocker, right?

[hidden email]  given that the system to run CI tests on the Python code embedded in the cookbook is already in place, what are the technical advantages of moving the cookbook into the Python API sphinx project?

 

Regards,
Harrissou

I think we should bring the documentation team into the discussion, is there a better place than this list where they have a better chance to get involved?

Cheers

--
Alessandro Pasotti
w3:   www.itopen.it
_______________________________________________
Qgis-psc mailing list
[hidden email]
https://lists.osgeo.org/mailman/listinfo/qgis-psc


--
Alessandro Pasotti
w3:   www.itopen.it
_______________________________________________
Qgis-psc mailing list
[hidden email]
https://lists.osgeo.org/mailman/listinfo/qgis-psc

_______________________________________________
Qgis-psc mailing list
[hidden email]
https://lists.osgeo.org/mailman/listinfo/qgis-psc
Reply | Threaded
Open this post in threaded view
|

Re: PyQgis Cookbook revision

pcav
Hi Harrissou,
I think everybody agrees in improving documentation, both for devs and
for users. Could you ask the proponents to put a formal proposal for
funding?
Cheers.

Il 27/02/20 10:20, DelazJ ha scritto:

> Hi PSC,
>
> I didn't want to ask during the feature freeze since I know Alessandro
> would anyway be busy with coding but now that it's over it would be nice
> to get a decision from the PSC whether the update of the cookbook as he
> proposed
> (http://osgeo-org.1560.x6.nabble.com/PyQgis-Cookbook-revision-tp5425519p5425665.html)
> could be done.
> Fwiw, I don't think that we should postpone that to grant proposal given
> that the docs might have their own budget and this fix should not be in
> competition with other areas of QGIS.
>
> Greetings
> Harrissou
>
> Le ven. 20 déc. 2019 à 15:41, Alexandre Neto <[hidden email]
> <mailto:[hidden email]>> a écrit :
>
>     In the docs meeting we have talked about splitting/removing the
>     python cookbook from the User manual (the same for other sections).
>
>     The advantages would be:
>
>     - We can release each document in separate
>     - We can break one of the docs without breaking the others
>     - we can have the cookbook more developers-oriented (even in the way
>     it's written)
>
>     The disadvantages would be:
>     - We would need to set intersphinx in both projects to allow keep
>     cross linking between them
>     - we would need to duplicate our sphinx project structure, and
>     maintain it (themes, makefiles, CI, etc...)
>     - If we want to go with translation, we would need to set other
>     transifex projects (at the meeting we kinda talked about the real
>     need for translation for the cookbook, quickly browsing excelpt for
>     spanish and french, most of other languages don't have it translated)
>
>     But anyway, like Alessandro said, the work that needs to be done,
>     can be performed in any of the repositories.
>
>     Alexandre Neto
>
>     On Fri, Dec 20, 2019 at 11:29 AM Alessandro Pasotti
>     <[hidden email] <mailto:[hidden email]>> wrote:
>
>
>
>         On Fri, Dec 20, 2019 at 12:22 PM DelazJ <[hidden email]
>         <mailto:[hidden email]>> wrote:
>
>             Hi all,
>
>             Quick points
>
>             Le ven. 20 déc. 2019 à 11:54, Alessandro Pasotti
>             <[hidden email] <mailto:[hidden email]>> a écrit :
>
>
>                 [...]
>
>                 Whether the whole Python developers guide (cookbook +
>                 API) is an external link or not is probably not so
>                 important, except maybe for browsability from the main
>                 website and search capabilities from the main website.
>
>             The intersphinx  extension helps to reach Python API
>             documentation from within the Cookbook or the User manual.
>             The reverse is not (yet?) true and I don't know whether it's
>             easy to do.
>
>                 Both the Python part and the C++ part are actually a mix
>                 of three separate topics:
>                 - core development (C++ and core Python plugins and
>                 processing core algs)
>                 - independent plugins (both C++ even if they are not
>                 very welcome lately and Python).
>                 - standalone applications
>
>                 In any event, if I get this right, moving the cookbook
>                 to a different sphinx project doesn't change much about
>                 the cookbook revision work I'm proposing to do, we can
>                 probably just move the doctest target into the python
>                 API project.
>
>                 But I wonder if moving the cookbook out of the
>                 documentation doesn't create a problem with
>                 translations, I didn't check if there are any for the
>                 cookbook.
>
>             Every document under qgis/QGIS-Documentation repository is
>             currently translated.
>
>
>
>         Hm, so I guess this is a blocker, right?
>
>         @Denis Rouzaud <mailto:[hidden email]>  given that the
>         system to run CI tests on the Python code embedded in the
>         cookbook is already in place, what are the technical advantages
>         of moving the cookbook into the Python API sphinx project?
>
>          
>
>
>             Regards,
>             Harrissou
>
>                 I think we should bring the documentation team into the
>                 discussion, is there a better place than this list where
>                 they have a better chance to get involved?
>
>                 Cheers
>
>                 --
>                 Alessandro Pasotti
>                 w3:   www.itopen.it <http://www.itopen.it>
>                 _______________________________________________
>                 Qgis-psc mailing list
>                 [hidden email] <mailto:[hidden email]>
>                 https://lists.osgeo.org/mailman/listinfo/qgis-psc
>
>
>
>         --
>         Alessandro Pasotti
>         w3:   www.itopen.it <http://www.itopen.it>
>         _______________________________________________
>         Qgis-psc mailing list
>         [hidden email] <mailto:[hidden email]>
>         https://lists.osgeo.org/mailman/listinfo/qgis-psc
>
>
> _______________________________________________
> Qgis-psc mailing list
> [hidden email]
> https://lists.osgeo.org/mailman/listinfo/qgis-psc
>

--
Paolo Cavallini - www.faunalia.eu
QGIS.ORG Chair:
http://planet.qgis.org/planet/user/28/tag/qgis%20board/
_______________________________________________
Qgis-psc mailing list
[hidden email]
https://lists.osgeo.org/mailman/listinfo/qgis-psc
Reply | Threaded
Open this post in threaded view
|

Re: PyQgis Cookbook revision

Alessandro Pasotti-2
On Sun, Mar 1, 2020 at 1:13 PM Paolo Cavallini <[hidden email]> wrote:
>
> Hi Harrissou,
> I think everybody agrees in improving documentation, both for devs and
> for users. Could you ask the proponents to put a formal proposal for
> funding?

The proponents is me, here is my proposal about the cookbook contents
revision (basically copied from my original email):

make a revision of the current cookbook text and code snippets in order to:
- update the text and the code snippets
- put ALL code snippets under the existing automated Python test CI
infrastructure.

The current situation (well, current when I wrote the original email
but I don't think it has changed):

- python code samples/snippets: 202
- python code samples/snippets currently tested: 53

My plan is:
1. check all the cookbook text for 3.10 (or whatever the LTR will be
when I will do the work) API changes and update it accordingly
2. put the 149 untested snippets under test

As far as point 1 is concerned the following files have the
'outofdate' directive:

./source/docs/pyqgis_developer_cookbook/server.rst
./source/docs/pyqgis_developer_cookbook/settings.rst
./source/docs/pyqgis_developer_cookbook/network_analysis.rst
./source/docs/pyqgis_developer_cookbook/canvas.rst
./source/docs/pyqgis_developer_cookbook/authentication.rst
./source/docs/pyqgis_developer_cookbook/plugins/ide_debugging.rst
./source/docs/pyqgis_developer_cookbook/plugins/pluginlayer.rst
./source/docs/pyqgis_developer_cookbook/plugins/releasing.rst
./source/docs/pyqgis_developer_cookbook/raster.rst

this of course doesn't mean that all others are necessarily uptodate,
but we can assume that they require less work to be updated.

It's a bit difficult to estimate the exact amount of work required to achieve
both tasks, especially because some code samples will require quite a lot
of setup and data in order to run in the automatic tests.

However, I think the most efficient way to proceed is to work on both
tasks simultaneously: while checking the code samples it will be easier
to also apply corrections to the text.

Total time required: 5 days at the standard QGIS hourly rate.

Note that in the original thread was discussed to move the cookbook
outside of the documentation, but that task is completely independent
from the text and code revision and it is not included in my proposal.

Regards.

--
Alessandro Pasotti
w3:   www.itopen.it
_______________________________________________
Qgis-psc mailing list
[hidden email]
https://lists.osgeo.org/mailman/listinfo/qgis-psc
Reply | Threaded
Open this post in threaded view
|

Re: PyQgis Cookbook revision

pcav
Thanks Ale.

On 1 March 2020 18:32:46 CET, Alessandro Pasotti <[hidden email]> wrote:
On Sun, Mar 1, 2020 at 1:13 PM Paolo Cavallini <[hidden email]> wrote:

Hi Harrissou,
I think everybody agrees in improving documentation, both for devs and
for users. Could you ask the proponents to put a formal proposal for
funding?

The proponents is me, here is my proposal about the cookbook contents
revision (basically copied from my original email):

make a revision of the current cookbook text and code snippets in order to:
- update the text and the code snippets
- put ALL code snippets under the existing automated Python test CI
infrastructure.

The current situation (well, current when I wrote the original email
but I don't think it has changed):

- python code samples/snippets: 202
- python code samples/snippets currently tested: 53

My plan is:
1. check all the cookbook text for 3.10 (or whatever the LTR will be
when I will do the work) API changes and update it accordingly
2. put the 149 untested snippets under test

As far as point 1 is concerned the following files have the
'outofdate' directive:

./source/docs/pyqgis_developer_cookbook/server.rst
./source/docs/pyqgis_developer_cookbook/settings.rst
./source/docs/pyqgis_developer_cookbook/network_analysis.rst
./source/docs/pyqgis_developer_cookbook/canvas.rst
./source/docs/pyqgis_developer_cookbook/authentication.rst
./source/docs/pyqgis_developer_cookbook/plugins/ide_debugging.rst
./source/docs/pyqgis_developer_cookbook/plugins/pluginlayer.rst
./source/docs/pyqgis_developer_cookbook/plugins/releasing.rst
./source/docs/pyqgis_developer_cookbook/raster.rst

this of course doesn't mean that all others are necessarily uptodate,
but we can assume that they require less work to be updated.

It's a bit difficult to estimate the exact amount of work required to achieve
both tasks, especially because some code samples will require quite a lot
of setup and data in order to run in the automatic tests.

However, I think the most efficient way to proceed is to work on both
tasks simultaneously: while checking the code samples it will be easier
to also apply corrections to the text.

Total time required: 5 days at the standard QGIS hourly rate.

Note that in the original thread was discussed to move the cookbook
outside of the documentation, but that task is completely independent
from the text and code revision and it is not included in my proposal.

Regards.

--
Alessandro Pasotti
w3: www.itopen.it

--
Please excuse my brevity.
_______________________________________________
Qgis-psc mailing list
[hidden email]
https://lists.osgeo.org/mailman/listinfo/qgis-psc
Reply | Threaded
Open this post in threaded view
|

Re: PyQgis Cookbook revision

pcav
In reply to this post by Alessandro Pasotti-2
Hi all,
any news on this? It seems a good idea, and I didn't see any objection.
Should we vote on the proposal?
Cheers.

Il 01/03/20 18:32, Alessandro Pasotti ha scritto:

> On Sun, Mar 1, 2020 at 1:13 PM Paolo Cavallini <[hidden email]> wrote:
>>
>> Hi Harrissou,
>> I think everybody agrees in improving documentation, both for devs and
>> for users. Could you ask the proponents to put a formal proposal for
>> funding?
>
> The proponents is me, here is my proposal about the cookbook contents
> revision (basically copied from my original email):
>
> make a revision of the current cookbook text and code snippets in order to:
> - update the text and the code snippets
> - put ALL code snippets under the existing automated Python test CI
> infrastructure.
>
> The current situation (well, current when I wrote the original email
> but I don't think it has changed):
>
> - python code samples/snippets: 202
> - python code samples/snippets currently tested: 53
>
> My plan is:
> 1. check all the cookbook text for 3.10 (or whatever the LTR will be
> when I will do the work) API changes and update it accordingly
> 2. put the 149 untested snippets under test
>
> As far as point 1 is concerned the following files have the
> 'outofdate' directive:
>
> ./source/docs/pyqgis_developer_cookbook/server.rst
> ./source/docs/pyqgis_developer_cookbook/settings.rst
> ./source/docs/pyqgis_developer_cookbook/network_analysis.rst
> ./source/docs/pyqgis_developer_cookbook/canvas.rst
> ./source/docs/pyqgis_developer_cookbook/authentication.rst
> ./source/docs/pyqgis_developer_cookbook/plugins/ide_debugging.rst
> ./source/docs/pyqgis_developer_cookbook/plugins/pluginlayer.rst
> ./source/docs/pyqgis_developer_cookbook/plugins/releasing.rst
> ./source/docs/pyqgis_developer_cookbook/raster.rst
>
> this of course doesn't mean that all others are necessarily uptodate,
> but we can assume that they require less work to be updated.
>
> It's a bit difficult to estimate the exact amount of work required to achieve
> both tasks, especially because some code samples will require quite a lot
> of setup and data in order to run in the automatic tests.
>
> However, I think the most efficient way to proceed is to work on both
> tasks simultaneously: while checking the code samples it will be easier
> to also apply corrections to the text.
>
> Total time required: 5 days at the standard QGIS hourly rate.
>
> Note that in the original thread was discussed to move the cookbook
> outside of the documentation, but that task is completely independent
> from the text and code revision and it is not included in my proposal.
>
> Regards.
>
> --
> Alessandro Pasotti
> w3:   www.itopen.it
>

--
Paolo Cavallini - www.faunalia.eu
QGIS.ORG Chair:
http://planet.qgis.org/planet/user/28/tag/qgis%20board/
_______________________________________________
Qgis-psc mailing list
[hidden email]
https://lists.osgeo.org/mailman/listinfo/qgis-psc
Reply | Threaded
Open this post in threaded view
|

Re: PyQgis Cookbook revision

Marco Bernasocchi-2
In reply to this post by Alessandro Pasotti-2
PSC VOTE
I accept the 5 day work on PyQGIS cookbook proposal by Alessandro (see below)

Marco +1

On Sun, 1 Mar 2020, 18:33 Alessandro Pasotti, <[hidden email]> wrote:
On Sun, Mar 1, 2020 at 1:13 PM Paolo Cavallini <[hidden email]> wrote:
>
> Hi Harrissou,
> I think everybody agrees in improving documentation, both for devs and
> for users. Could you ask the proponents to put a formal proposal for
> funding?

The proponents is me, here is my proposal about the cookbook contents
revision (basically copied from my original email):

make a revision of the current cookbook text and code snippets in order to:
- update the text and the code snippets
- put ALL code snippets under the existing automated Python test CI
infrastructure.

The current situation (well, current when I wrote the original email
but I don't think it has changed):

- python code samples/snippets: 202
- python code samples/snippets currently tested: 53

My plan is:
1. check all the cookbook text for 3.10 (or whatever the LTR will be
when I will do the work) API changes and update it accordingly
2. put the 149 untested snippets under test

As far as point 1 is concerned the following files have the
'outofdate' directive:

./source/docs/pyqgis_developer_cookbook/server.rst
./source/docs/pyqgis_developer_cookbook/settings.rst
./source/docs/pyqgis_developer_cookbook/network_analysis.rst
./source/docs/pyqgis_developer_cookbook/canvas.rst
./source/docs/pyqgis_developer_cookbook/authentication.rst
./source/docs/pyqgis_developer_cookbook/plugins/ide_debugging.rst
./source/docs/pyqgis_developer_cookbook/plugins/pluginlayer.rst
./source/docs/pyqgis_developer_cookbook/plugins/releasing.rst
./source/docs/pyqgis_developer_cookbook/raster.rst

this of course doesn't mean that all others are necessarily uptodate,
but we can assume that they require less work to be updated.

It's a bit difficult to estimate the exact amount of work required to achieve
both tasks, especially because some code samples will require quite a lot
of setup and data in order to run in the automatic tests.

However, I think the most efficient way to proceed is to work on both
tasks simultaneously: while checking the code samples it will be easier
to also apply corrections to the text.

Total time required: 5 days at the standard QGIS hourly rate.

Note that in the original thread was discussed to move the cookbook
outside of the documentation, but that task is completely independent
from the text and code revision and it is not included in my proposal.

Regards.

--
Alessandro Pasotti
w3:   www.itopen.it
_______________________________________________
Qgis-psc mailing list
[hidden email]
https://lists.osgeo.org/mailman/listinfo/qgis-psc

_______________________________________________
Qgis-psc mailing list
[hidden email]
https://lists.osgeo.org/mailman/listinfo/qgis-psc
12