[QGIS-Developer] Documentation wish list for "hackfesters"

[DelazJ]

Hi all,

With the QGIS Community Meeting beginning, a bunch of developers and
writers will meet to brainstorm and improve QGIS. Here are some suggestions
of topics (among many others) some documentation contributors would be
REALLY interested in having a fix for. We need a developer to address and
ease our "life" (sounds tragical enough? :D ). Well.

In short:
1/ *Improve the automatic creation of screenshots* [1]
2/ *Redirect docs links *and ensure that changing links in docs does *not
break the help button* in application [3]
3/ *Document/improve the doctest architecture for PyQGIS Cookbook *(kind of
[4])

For the details:
1/ QGIS is moving fast. Dialogs are changing at every release, making
screenshots in the docs obsolete. There was a plan to avoid writers
manually take each screenshot, and instead generate them in series,
browsing tabs of a specified dialog eg. A work had been initiated in the
QgsAppScreenshots class [1]. It could be nice to get more news on it.
Incidentally, with such a feature, we can expect more translated
screenshots (which may not be good for our server but helpful for
non-English readers and translators).

2/ Because features are getting bigger, we sometimes need to reorganize the
chapters in documentation in order to match how things behave in the
application and also avoid very loooong chapters. Moving sections or
renaming them (to match their actual scope) breaks the Help button
associated to the feature, for at least three releases (the next-to-be LTR
and the two previous versions since they point to the same doc). To fix
that, doc writers have to update the links in the code and this change only
applies to current release(s), not for EOLed one (eg 3.6 could have more
not working links than 3.8 or master - we have a script for checks [2]).
We need to find a more viable way to address this issue and redirect
requested links to their actual place in the corresponding doc.
This issue is a long standing one that has been reported/discussed a couple
of times already (eg [3] has some suggestions)

3/ During the La Coruna hackfest, a doctest infrastructure has been set up
to ensure code samples provided for PyQGIS Cookbook are still working.
Months later, it looks to me like it's less used than it should:
 - partly, because we did not make it mandatory,
 - partly because it does not apply (or we did not figure out how?) in some
cases. Eg it seems it does not know about iface [4]. Also there are test
projects the system should rely on but nobody uses it and afaics there's no
example someone not used to this could follow.
It could be nice clarifying the system and help writers adopt it.

[1] https://github.com/qgis/QGIS/blob/master/src/app/qgsappscreenshots.h
[2] https://github.com/qgis/QGIS/blob/master/scripts/chkdoclink.sh
[3]
https://github.com/qgis/QGIS-Documentation/pull/2258#issuecomment-352246124
[4] https://github.com/qgis/QGIS-Documentation/issues/3776

Et voilà... Sorry to have been long. Looking forward...
And for information, docs still have unallocated founds...

Happy hackfest,
Harrissou
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.osgeo.org/pipermail/qgis-developer/attachments/20190823/0dab03c6/attachment.html>