<div dir="ltr"><div dir="ltr"><br></div><br><div class="gmail_quote"><div dir="ltr" class="gmail_attr">On Fri, Dec 20, 2019 at 11:26 AM Denis Rouzaud <<a href="mailto:denis.rouzaud@gmail.com">denis.rouzaud@gmail.com</a>> wrote:<br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><div dir="auto"><div>Hi Ale,<div dir="auto"><br></div><div dir="auto">Sorry for not being clear.</div><br><br><div class="gmail_quote"><div dir="ltr" class="gmail_attr">Le jeu. 19 déc. 2019 à 16:59, Alessandro Pasotti <<a href="mailto:apasotti@gmail.com" target="_blank">apasotti@gmail.com</a>> a écrit :<br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><div dir="ltr"><div dir="ltr"><br></div><br><div class="gmail_quote"><div dir="ltr" class="gmail_attr">On Thu, Dec 19, 2019 at 4:41 PM Denis Rouzaud <<a href="mailto:denis.rouzaud@gmail.com" rel="noreferrer" target="_blank">denis.rouzaud@gmail.com</a>> wrote:<br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><div dir="ltr">Hi all,<div><br></div><div>I was wondering if the cookbook could be integrated with the API docs website.</div><div>It would be nice, we could test everything there (it uses the QGIS docker images), and it would have a single coherente endpoint.</div><div><br></div><div>Ale, feel free to get in touch :)</div><div><br></div><div>Denis</div></div></blockquote><div><br></div><div>Hi Denis,</div><div><br></div><div>Do you you mean adding the cookbook directly in the C++ class headers? Like <a href="https://github.com/qgis/QGIS/blob/master/src/server/qgsserverogcapi.h#L33" rel="noreferrer" target="_blank">https://github.com/qgis/QGIS/blob/master/src/server/qgsserverogcapi.h#L33</a> ?</div><div><br></div><div>This is what QT does, right?</div><div><br></div><div>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). <br></div><div>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. <br></div><div><br></div><div>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.</div></div></div></blockquote></div></div><div dir="auto"><br></div><div dir="auto"><br></div><div dir="auto">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.</div><div dir="auto"><div class="gmail_quote"><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><div dir="ltr"><div class="gmail_quote"><div></div><div><br></div><div>In any event, the cookbook also uses a QGIS docker image for the python code tests (qgis/qgis:latest).</div><div><br></div><div>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.<br></div></div></div></blockquote></div></div><div dir="auto"><br></div><div dir="auto"><br></div><div dir="auto">Yes, I have 2 points:</div><div dir="auto">* Build the API docs and the cookbook in the same job (but I don't care that much if not)</div><div dir="auto">* Bring the cookbook under the same website as <a href="http://qgis.org/pyqgis" target="_blank">qgis.org/pyqgis</a> so we have a single entry for all python related stuff.</div><div dir="auto"><br></div><div dir="auto">Cheers</div><div dir="auto">Denis</div><div dir="auto"><br></div></div>
</blockquote></div><div><br></div><div>Hi Denis, <br></div><div><br></div><div>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:</div><div><br></div><div>- C++ API website</div><div>- Python API website</div><div>- Documentation website</div><div> - developers guide (C++ oriented)<br></div><div> - python cookbook (Python oriented)<br></div><div><br></div><div>(One bad thing is that they have complete different look and feel, but that's another story)</div><div><br></div><div>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:</div><div><br></div><div><div>- Documentation website</div><div> - developers docs</div><div> - generic material about PRs, code of conduit etc.<br></div><div> - C++ developers guide</div><div> - link to the C++ API<br></div><div> - Python developers guide (the cookbook)<br></div><div> - link to Python API<br></div></div><div><br></div><div>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.</div><div><br></div><div>Both the Python part and the C++ part are actually a mix of three separate topics: <br></div><div>- core development (C++ and core Python plugins and processing core algs) <br></div><div>- independent plugins (both C++ even if they are not very welcome lately and Python).</div><div>- standalone applications <br></div><div><br></div><div>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.</div><div><br></div><div>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.</div><div><br></div><div>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?<br></div><div><br></div><div>Cheers<br></div><div><br></div>-- <br><div dir="ltr" class="gmail_signature">Alessandro Pasotti<br>w3: <a href="http://www.itopen.it" target="_blank">www.itopen.it</a></div></div>