Status of context help

[DelazJ]

Many dialogs have a help button to show a context help which hasn't been updated for a while, although the dialog has evolved with new/removed features.
It might be nice to get rid of those useless buttons or rethink a way to link them to a doc repo. Some on-going (or pending?) discussions around this:

• QEP 32: Generic Helping System for QGIS
• Reorganize the help system

[SrNetoChan]

This is a major UX fail. I would say that the built-in help as it is, is useless. Therefore, to start, we should replace it by links to online documentation. We might have some problems with this because normally the documentations is not released at the same pace as QGIS itself. We need a strategy to point to the latest available documentation if the current QGIS version is not available. If possible, the GUI language should be used to open, if existent, the help doc in the current language.

Then we have the problem of Offline help. It should be possible for users to download the documentation to use in offline enviroments. The system should allow to:

• Download and use different language packages
• Update documentation (when a new version is released)
  This could be achived with plugins or with the resource sharing plugin (better)

So, when the user click help QGIS would:

• check for connectivity,
• if there connectivity do:
  • check for documentation in GUI language
  • default to ENglish if not existent
• if there is no connectivity
  • search local documentation in GUI language
  • If not, search for english documentation

[DelazJ]

I'd say that doc checking should be first local and if that fails, online. It shouldn't be related to connectivity availability. Connectivity might be there but slow or expensive. Once the person has opted for a local doc (meaning that there is an option to choose to download doc or use online one), there's no reason to go and use the online one. It could also be proposed (or silently done) with desktop release point, an update of the doc too (until now, translation of new strings has occurred after the release of the doc which occurs after the desktop x.x.0 release). But all this is a second step debate.

I don't know how technically linking the desktop to doc repo could be done but it'll require more investment in doc writing (to have it available, at least in English with the major release and not 2 versions later) but also a strict organization of the doc, to ensure permanent link from release to release (is it possible to use internal hyperlink, which ensures stability on reaching the section, even if moved under another chapter?).
Some attempts of showing online doc in desktop have been done with processing few releases ago. Might be nice to share their experience.

[pcav]

IMHO we really have to fix this for QGIS3.
Thanks for raising the issue.

[alexbruy]

This related not only for context help, but for help system in general. For example we want to provide users with Processing algs help (both native and 3rd party), GRASS plugin also may want to display module help etc.

Also it would be nice to have some generic mechanism which can be reused by plugins.

[alexbruy]

PR which implements qgis/QGIS-Enhancement-Proposals#51 merged in master. So we can start with adopting docs, merging context help and linking them from QGIS

[SrNetoChan]

@alexbruy Can you provide instructions on how to adopt the context help to point to Docs URL, for "normal" people like me?

@rduivenvoorde If I recall, you once mention having a list with all help buttons and which section in docs they should point to. Do you still have it?

Thanks

[DelazJ]

@SrNetoChan

@rduivenvoorde If I recall, you once mention having a list with all help buttons and which section in docs they should point to. Do you still have it?

You might be looking for http://hub.qgis.org/wiki/quantum-gis/ContextHelp

[alexbruy]

@SrNetoChan you can look at qgis/QGIS#4023 for some examples.

[DelazJ]

@alexbruy I played a bit with the help system recently and It looks like that the current implementation is not as described above by @SrNetoChan. If I understand the behavior in qgis, doc fetching is based on the order of the "repo" set. The upper the source is, the earlier it's checked and if no result found, the source below is tested, and so on, regardless online vs offline or English vs localized priority matters. Do I get the scheme?
I'm kind of fine with this behavior as it gives to any user capabilities to easily manage and select the documentation (and language) he prefers.
But I think we should provide default links (issue report at http://hub.qgis.org/issues/16155), either as examples for people that would like to add other links as to provide a working environment, out of the box. These default links would be:

• Last released doc (probably the LTR) - should it defaulted to English or localized (if applicable)" looks like a question we should answer )
• Testing doc

However I don't know in which order: eg, for a Spanish user working with QGIS 3.0, is it better to get a 2.14 Spanish documentation (probably outdated) than an English-only Testing doc (probably more up to date)? For New features (eg. Dxf import, geopackage) that have a dedicated section, the Testing, hence English doc, will be anyway returned in the meantime.

[jgrocha]

Current status

New context help

C++

Looking for: QgsHelp::openHelp( on *.h and *.cpp

find . \( -name \*.h -o -name \*.cpp \) -exec grep -H "QgsHelp::openHelp(" \{\} \; | sed 's/:[^"]\+/\t/;s/" .\+$/"/' | sed 's/\.\/src\///' | sort | awk -F $'\t' '{print "|" $1 "|" $2 "|";}' | grep -v "||" | sed 's/"//g'

Usage results (34)

File	Documentation URL
app/pluginmanager/qgspluginmanager.h	plugins/plugins.html#the-plugins-dialog
app/qgisapp.cpp	index.html
app/qgscustomprojectiondialog.h	working_with_projections/working_with_projections.html#custom-coordinate-reference-system
app/qgsdecorationcopyrightdialog.cpp	introduction/general_tools.html#copyright-label
app/qgsdecorationgriddialog.cpp	introduction/general_tools.html#grid
app/qgsdecorationnortharrowdialog.cpp	introduction/general_tools.html#north-arrow
app/qgsdecorationscalebardialog.cpp	introduction/general_tools.html#scale-bar
app/qgsidentifyresultsdialog.h	introduction/general_tools.html#identify
app/qgsmeasuredialog.h	introduction/general_tools.html#measuring
app/qgsnewspatialitelayerdialog.h	working_with_vector/editing_geometry_attributes.html#vector-create-spatialite
app/qgsoptions.h	introduction/qgis_configuration.html#options
app/qgsprojectproperties.h	introduction/qgis_configuration.html#project-properties
app/qgsrasterlayerproperties.h	working_with_raster/raster_properties.html
app/qgsvectorlayerproperties.h	working_with_vector/vector_properties.html
gui/ogr/qgsopenvectorlayerdialog.h	working_with_vector/supported_data.html#loading-a-layer-from-a-file
gui/ogr/qgsvectorlayersaveasdialog.h	introduction/general_tools.html#save-layer-into-file
gui/qgsnewvectorlayerdialog.h	working_with_vector/editing_geometry_attributes.html#creating-a-new-shapefile-layer
gui/qgsquerybuilder.h	working_with_vector/vector_properties.html#query-builder
gui/symbology-ng/qgsstylemanagerdialog.h	working_with_vector/style_library.html#id2
plugins/coordinate_capture/coordinatecapturegui.h	plugins/plugins_coordinate_capture.html
plugins/evis/databaseconnection/evisdatabaseconnectiongui.h	plugins/plugins_evis.html#database-connection
plugins/gps_importer/qgsgpsplugingui.h	working_with_gps/plugins_gps.html
plugins/offline_editing/offline_editing_plugin_gui.cpp	plugins/plugins_offline_editing.html
providers/db2/qgsdb2newconnection.h	working_with_vector/supported_data.html#db2-spatial-layers
providers/db2/qgsdb2sourceselect.h	working_with_vector/supported_data.html#db2-spatial-layers
providers/delimitedtext/qgsdelimitedtextsourceselect.h	working_with_vector/supported_data.html#delimited-text-files
providers/mssql/qgsmssqlnewconnection.h	working_with_vector/supported_data.html#mssql-spatial-layers
providers/mssql/qgsmssqlsourceselect.h	working_with_vector/supported_data.html#mssql-spatial-layers
providers/oracle/qgsoraclenewconnection.h	working_with_vector/supported_data.html#oracle-spatial-layers
providers/oracle/qgsoraclesourceselect.h	working_with_vector/supported_data.html#oracle-spatial-layers
providers/postgres/qgspgnewconnection.h	working_with_vector/supported_data.html#postgis-layers
providers/postgres/qgspgsourceselect.h	working_with_vector/supported_data.html#postgis-layers
providers/spatialite/qgsspatialitesourceselect.h	working_with_vector/supported_data.html#spatialite-layers
providers/wms/qgswmssourceselect.h	working_with_ogc/ogc_client_support.html#wms-wmts-client

Python

Only python/plugins/processing/gui/AlgorithmDialogBase.py is using the new context help system.

from qgis.gui import QgsHelp

algHelp = QgsHelp.helpUrl("processing_algs/{}/{}".format(
                self.alg.provider().id(), self.alg.id())).toString()

[jgrocha]

First script checkdoclink.sh

First attempt to create a script to check if all documentaion mentioned in the code exist...

#!/bin/bash

find . \( -name \*.h -o -name \*.cpp \) -exec grep -H "QgsHelp::openHelp(" \{\} \; | grep QStringLiteral | sed 's/^[^"]\+"//;s/" .\+$//' | awk '{print "http://docs.qgis.org/testing/en/docs/user_manual/" $1}' | while read link; do
    # echo "URL to check: $link"
    if ! wget --spider $link 2>/dev/null; then
        echo "Documentation missing: " $link
    fi
done

jgr@dusseldorf:~/dev/QGIS$ ./checkdoclink.sh
Documentation missing:  http://docs.qgis.org/testing/en/docs/user_manual/working_with_vector/supported_data.html#postgis-layers
Documentation missing:  http://docs.qgis.org/testing/en/docs/user_manual/working_with_vector/supported_data.html#postgis-layers
Documentation missing:  http://docs.qgis.org/testing/en/docs/user_manual/working_with_vector/supported_data.html#delimited-text-files
Documentation missing:  http://docs.qgis.org/testing/en/docs/user_manual/working_with_vector/supported_data.html#db2-spatial-layers
Documentation missing:  http://docs.qgis.org/testing/en/docs/user_manual/working_with_vector/supported_data.html#db2-spatial-layers
Documentation missing:  http://docs.qgis.org/testing/en/docs/user_manual/working_with_vector/supported_data.html#mssql-spatial-layers
Documentation missing:  http://docs.qgis.org/testing/en/docs/user_manual/working_with_vector/supported_data.html#mssql-spatial-layers
Documentation missing:  http://docs.qgis.org/testing/en/docs/user_manual/working_with_vector/supported_data.html#oracle-spatial-layers
Documentation missing:  http://docs.qgis.org/testing/en/docs/user_manual/working_with_vector/supported_data.html#oracle-spatial-layers
Documentation missing:  http://docs.qgis.org/testing/en/docs/user_manual/working_with_vector/supported_data.html#spatialite-layers
Documentation missing:  http://docs.qgis.org/testing/en/docs/user_manual/working_with_vector/supported_data.html#loading-a-layer-from-a-file

[DelazJ]

@jgrocha

Looking for: QgsHelp::openHelp( on *.h and *.cpp
find . \( -name \*.h -o -name \*.cpp \) -exec grep -H "QgsHelp::openHelp(" \{\} \; | sed 's/:[^"]\+/\t/;s/" .\+$/"/' | sed 's/\.\/src\///' | sort | awk -F $'\t' '{print "|" $1 "|" $2 "|";}' | grep -v "||" | sed 's/"//g'
Usage results (34)

When I think that i had spent hours to rebuild and check this list, i'm just full of frustration for ignoring this kind of cool commands. I definitively need to learn that!

First attempt to create a script to check if all documentaion mentioned in the code exist...

Interesting! then you'd need to map it with the source file, right? I have many other questions but i prefer not to disturb you with them yet and let you draw "your" system.
Btw, note that there's PR qgis/QGIS#4941 to fix these links but good that it was not merged before your tests

[DelazJ]

Ah... And Thanks !

[jgrocha]

Current status of the former Helpviewer (C++ usage)

find src \( -name \*.h -o -name \*.cpp \) -exec grep -H "QgsContextHelp::run(" \{\} \; | grep -v "//" | grep -v "qgscontexthelp" | sed 's/^src\///;s/:.*$//' | awk '{ print "|" $1 "|" }'

Usage (14 cases)

File/Class
app/qgsfieldcalculator.h
providers/wfs/qgswfssourceselect.h
providers/wms/qgswmtsdimensions.h
providers/arcgisrest/qgsarcgisservicesourceselect.cpp
plugins/plugin_template/plugingui.cpp
gui/qgsnewhttpconnection.h
gui/qgssublayersdialog.h
gui/qgsprojectionselectiondialog.h
gui/qgsnewgeopackagelayerdialog.h
gui/qgssearchquerybuilder.h
gui/qgssqlcomposerdialog.h
gui/ogr/qgsnewogrconnection.h

Current status of the former Helpviewer (Python usage)

Usage (1 case)

File/Class
python/console/console.py

[DelazJ]

Closing... as context helps have been removed from repo and despite the numerous missing "connected help buttons"