[QGIS-Developer] Let's bring documentation at the heart of QGIS Desktop...

[DelazJ]

 Hi QGIS-ers,

As you might know, QGIS3 will get rid of the current (mainly) outdated
context help dialogs. These were not really maintained for years, and hard
to translate (a big piece of text, full of html tags, that you have to
rework when a single letter changes).

Now, Hitting the help button in a dialog should open:
- the neither fully up-to-date but heartily maintained official and online
doc
- or a local zipped doc.
Specifications were brought to discussion in QEP 51 [0] and UIX repo [1].
Afaik only the online doc relation infrastructure has been implemented for
the moment (at least it's the only one I had tested and once customized, it
works pretty good though some limitations - see the needed improvements
summary at [2] ).

The next step is to link all help buttons to the proper section in the
documentation.
Actually, I found out there are a lot of dialogs (older as well as newly
created) without a proper help button so I began a list in the uix issue
reports repository [3]. If you want to help add the missing button, please
feel free to do it. And please check the fixed items in the list to ease
the track.

Going further and based on an initial work of Richard Duivenvoorde
(Thanks!), I set up a list with most of the existing dialogs and panels in
QGIS (around 200), with their corresponding section in doc (if exists), and
whether there's already a help button, the file in which to add the doc
link (needs completion) and if  the relation is already set or not.
The rationale of this file has been mentioned at [4] but I'd like to add
that imho this db could be used as references to keep up-to-date help
"dialogs". We can imagine a kind of magic commands from you devs, that
automatically do the matching between the two repositories based on this
list and updating that list will fix links without a need to manually set
it in each resource file. I don't know if that's possible but it could be
nice i think.
What are left to do:
- Complete the list of resource files, in which the commands to open the
help link is se, and find missing dialogs (I couldn't dig all dialogs)
- Add the help button (or icon) where appropriate
- Set the relation to documentation pages
- Keep the table up-to-date

Giving a look to the QGIS code, I found that some links are added in the .h
while others are in the .cpp one, sometimes as private slots or public
ones. Can't figure out why so to avoid losing time  (I'm afraid I had spent
enough) and for a better subsidiarity, I think it's better to have
developers handle that part of the "job".

The whole file is available as a collaborative Framadate Calc at [5]. I
didn't find the markdown of the wiki or issue reports easily maintainable.
Sorry the interface is in French but icons should help and it's fully Open
Source :) . However, if you want to move it to a place that would be more
linked with QGIS infrastructure, feel free.

Hoping that will be useful to the Project...

Regards,
Harrissou

[0] QEP 51- https://github.com/qgis/QGIS-Enhancement-Proposals/issues/51
[1] UIX discussion https://github.com/qgis/qgis3_UIX_discussion/issues/15
<https://github.com/qgis/qgis3_UIX_discussion/issues/15.>
[2] QGIS 3 doc wiki https://github.com/DelazJ/QGIS
-Documentation/wiki/On-the-road-to-QGIS3#relation-between-
qgis-docs-and-desktop
[3] Some dialogs missing help button https://github.com/qgis/qgis3_
UIX_discussion/issues/33
<https://github.com/qgis/qgis3_UIX_discussion/issues/33.>
[4] https://github.com/qgis/QGIS/pull/4135
[5] Find the Data - https://framacalc.org/4hipbz1q7t
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.osgeo.org/pipermail/qgis-developer/attachments/20170729/16f9ab38/attachment.html>