[Qgis-psc] PyQgis Cookbook revision

[Alessandro Pasotti]

On Fri, Dec 20, 2019 at 11:26 AM Denis Rouzaud <denis.rouzaud at gmail.com>
wrote:

> Hi Ale,
>
> Sorry for not being clear.
>
>
> Le jeu. 19 déc. 2019 à 16:59, Alessandro Pasotti <apasotti at gmail.com> a
> écrit :
>
>>
>>
>> On Thu, Dec 19, 2019 at 4:41 PM Denis Rouzaud <denis.rouzaud at gmail.com>
>> 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
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.osgeo.org/pipermail/qgis-psc/attachments/20191220/55af34da/attachment.html>