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

[DelazJ]

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