<div dir="ltr"><div>Hi all,</div><div><br></div><div>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.</div><div><br></div><div>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):</div><div><br></div><div>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.<br></div><div>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. <br></div><div><br></div><div>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].</div><div>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?</div><div></div><div>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:</div><div>- we need people to pick each<br></div><div>- there isn't a way (or we don't know how) to test iface in the codes, resulting in many interface-related codes untestable.</div><div><br></div><div>Hope that clarifies, and may those who were parts of this feel free to correct if I miss anything.</div><div><br></div><div>Regards,</div><div>Harrissou<br></div><div><br></div><div>[0] <a href="http://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html">http://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html</a></div><div>[1] <a href="https://github.com/qgis/QGIS-Documentation/blob/master/source/conf.py#L113">https://github.com/qgis/QGIS-Documentation/blob/master/source/conf.py#L113</a></div><div>[2] <a href="https://docs.qgis.org/testing/en/docs/user_manual/processing/console.html#creating-scripts-and-running-them-from-the-toolbox">https://docs.qgis.org/testing/en/docs/user_manual/processing/console.html#creating-scripts-and-running-them-from-the-toolbox</a></div><div>[3] <a href="http://www.sphinx-doc.org/en/master/usage/extensions/doctest.html">http://www.sphinx-doc.org/en/master/usage/extensions/doctest.html</a></div><div>[4] <a href="https://github.com/qgis/QGIS-Documentation#testing-python-snippets">https://github.com/qgis/QGIS-Documentation#testing-python-snippets</a></div><div>[5] <a href="https://github.com/qgis/QGIS-Documentation/pull/3406#issuecomment-458462153">https://github.com/qgis/QGIS-Documentation/pull/3406#issuecomment-458462153</a></div></div>