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

[DelazJ]

Hi all,

The hackfest has gone for weeks, but QGIS is still there as well as writers
and developers. So I wonder if someone had considered the opportunity to
give a hand on any of the identified issues.

*NB: It could not be for the "Spare Time Inc" since we still have
unallocated funds (and not "founds" - damn keyboard).*

Regards,
Harrissou

Le ven. 23 août 2019 à 18:21, DelazJ <delazj at gmail.com> a écrit :

> 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/20190916/75ac47c0/attachment.html>