Bug report #17231

Processing help system expects wrong link

Added by Harrissou Santanna over 2 years ago. Updated about 2 years ago.

Status:Closed
Priority:Normal
Assignee:Victor Olaya
Category:Processing/Core
Affected QGIS version:master Regression?:No
Operating System: Easy fix?:No
Pull Request or Patch supplied:No Resolution:fixed/implemented
Crashes QGIS or corrupts data:No Copied to github as #:25130

Description

When hitting the Help button in a Processing tool dialog, the expected link doesn't follow the same structure than links of QGIS Documentation.
For example if I hit the "Merge Vector Layers" tool under QGIS/Vector General group, I will get 'testing/en/docs/user_manual/processing_algs/qgis/ qgis:mergevectorlayers' while doc link is 'testing/en/docs/user_manual/processing_algs/qgis/ vector_general_tools.html#merge-vector-layers'

Associated revisions

Revision 2d1e9188
Added by Nyall Dawson about 2 years ago

[processing] Allow providers to return a different helpId() vs
their unique id()

This is used when generating the QgsHelp url for algorithms
attached to the providers.

Implement helpId overrides for the native and 3d providers so
that they return 'qgis' helpIds, meaning that all QGIS processing
algorithm documentation can be kept within the same url path
regardless of which QGIS provider library it sits within.

This also allows us to freely move algorithms from the Python
'qgis' provider to c++ 'native' provider in future releases
without breaking the help URLs.

Fixes #17231

History

#1 Updated by Alexander Bruy over 2 years ago

  • Status changed from Open to Feedback

I don't think this is an issue, as QGIS documentation for master is not ready yet and we can't be 100% sure that current structure won't change anymore. I suggest close this and update links only when QGIS documentation structure will be mature.

#2 Updated by Harrissou Santanna over 2 years ago

I don't think this is an issue, as QGIS documentation for master is not ready yet and we can't be 100% sure that current structure won't change anymore

The issue i'm reporting is about the structure of the link (using : instead of # and prepending qgis instead of group name) and I think it's valid, even if as you pointed the work on Processing algs is not yet finished. But:

- the Processing doc structure currently follows how algs are grouped in QGIS so i fail to see what kind of changes would make it better fit the application and easily found out by users
- I'm not aware of any (public) plan to reorganize the structure of the documentation (be it the whole manual or only Processing part) other than filling the algs description and usage, and polishing a bit the visual look of this chapter. But I might have missed the information.
- I'm not sure that the way Sphinx generates documentation links will change and meet what we expect from QGIS help button, without some subsequent work. And if QGIS-Documentation can benefit from a dev time for that, I'd rather advocate other long standing structural issues (eg., improve search tool results, ensure fallback to english and/or testing doc when wrong link....)

#3 Updated by Alexander Bruy over 2 years ago

Harrissou Santanna wrote:

- the Processing doc structure currently follows how algs are grouped in QGIS so i fail to see what kind of changes would make it better fit the application and easily found out by users

Please note that in its current state Processing docs relies on the groups and algorithms names which are localized and will be different for different locales. Same with provider names. IMHO all of these should rely on the corresponding ids which are used internally and non-translatable.

I don't know much about how documentation team decide which structure to use for documentation. Just took couple of random algorithms from the Processing docs and URLs appear to have slightly different structure:

What I'm trying to say is that we need some standard URL scheme for all providers, we should avoid translatable strings in the URLs.

- I'm not aware of any (public) plan to reorganize the structure of the documentation (be it the whole manual or only Processing part) other than filling the algs description and usage, and polishing a bit the visual look of this chapter. But I might have missed the information.

Neither am I, that's why I'm asking.

#4 Updated by Harrissou Santanna over 2 years ago

Currently, few algorithms have been rewritten so it's normal that you find errors. Only these groups are done https://github.com/qgis/QGIS-Documentation/pulls?q=is%3Apr+is%3Aclosed+label%3A%22Processing+help%22. And the fix will follow the same structure for ALL algorithms (provider/group.html#algname)- actually the URL is built like this by Sphinx (and I don't know if we can override it - is it desirable?) but we chose to use same terms like in the application and in that sequence.

Let's take the database group (http://docs.qgis.org/testing/en/docs/user_manual/processing_algs/qgis/database.html) which has been reworked. All the listed algs are shown the way they are in QGIS and if you check the link it follows the structure "provider/group.html#algorithmNameWithSpaceReplacedByHyphen" ie http://docs.qgis.org/testing/en/docs/user_manual/processing_algs/qgis/database.html#spatialite-execute-sql. I don't see the issue you mention about localization. This link will not change except for the language code part, right?
At the same time QGIS help button tries to open http://docs.qgis.org/testing/en/docs/user_manual/processing_algs/qgis/qgis:spatialite-execute-sql.
Is it not easier for QGIS to follow the provider/group.html#algname scheme?

IMHO all of these should rely on the corresponding ids which are used internally and non-translatable.

About the use of the internal link, do you mean the anchors placed in the rst files that help do cross link pages? Is that technically possible? I had asked the question months ago without any answer because that will be a nice way to ensure that documentation is always reachable from help button, even if we reorganize chapters (I'm particularly thinking about the User Manual - the current use of the url somehow freezes pages and does not really allow to move sections from a chapter to another). No dead link to docs whatever QGIS version is used.

#5 Updated by Alexander Bruy over 2 years ago

Harrissou Santanna wrote:

Let's take the database group (http://docs.qgis.org/testing/en/docs/user_manual/processing_algs/qgis/database.html) which has been reworked. All the listed algs are shown the way they are in QGIS and if you check the link it follows the structure "provider/group.html#algorithmNameWithSpaceReplacedByHyphen" ie http://docs.qgis.org/testing/en/docs/user_manual/processing_algs/qgis/database.html#spatialite-execute-sql. I don't see the issue you mention about localization. This link will not change except for the language code part, right?

No. For example, URL you mentioned with Ukrainian locale will look like http://docs.qgis.org/testing/en/docs/user_manual/processing_algs/qgis/базыданных.html#выполнить-sql-запрос-spatialite

#6 Updated by Harrissou Santanna over 2 years ago

Alexander Bruy wrote:

No. For example, URL you mentioned with Ukrainian locale will look like http://docs.qgis.org/testing/en/docs/user_manual/processing_algs/qgis/базыданных.html#выполнить-sql-запрос-spatialite

That's rather weird. In the french locale, the last bits of the url are not translated. Still from the french locale, switching to japan, korean or russian (there seems to not be ukrainian on 2.18) the URL neither changes except for the language code part. Whatever language i try, the english source text is always used.
Then, the issue should also reside in the QGIS dialogs Help system, shouldn't it? Is that different?

#7 Updated by Alexander Bruy over 2 years ago

Harrissou Santanna wrote:

In the french locale, the last bits of the url are not translated.

Just curious where you found french docs for master?

#8 Updated by Harrissou Santanna over 2 years ago

Alexander Bruy wrote:

Just curious where you found french docs for master?

You know that it does not exist. I meant, if using uk locale, "database" and "spatialite-execute-sql" are translated, in fr i would also expect these translations. Something i do not get.
Do we have some weird config for QGIS-Docs or is it the way url works with non latin characters (sorry, i'm not used to them)?

No. For example, URL you mentioned with Ukrainian locale will look like http://docs.qgis.org/testing/en/docs/user_manual/processing_algs/qgis/базыданных.html#выполнить-sql-запрос-spatialite

Does it also mean that serving the fully english link (http://docs.qgis.org/testing/en/docs/user_manual/processing_algs/qgis/database.html#spatialite-execute-sql) returns an error in uk? If the page is found and only the url is translated for convenience at the end, then there's no real issue, as long as we provide valid and existing links...

#9 Updated by matteo ghetta over 2 years ago

Let me step in in this discussion, actually sorry for the delay ;)

Besides the (eventual) locale problems I see also 2 potentially coding issues:

1. if the algorithm provider is the so called native (but the docs are in the qgis provider) the link is not correctly build. For example for the native Clip algorithm, this is the wrong link:

http://docs.qgis.org/testing/en/docs/user_manual/processing_algs/native/native:clip

where native should be replaced by qgis.

2. the name of the algorithm groups in the docs are different from the code one. For example the Intersection algorithm:

  • in the code the group is Vector overlay
  • in the docs is in vector_overlay_tools

In this case I think we can (should?) change the name of the docs files instead of the algorithm group parameter.

#10 Updated by Paolo Cavallini about 2 years ago

Wouldn't it be better to redirect to a page "docs missing - please write your and send it to ..."?

#11 Updated by Harrissou Santanna about 2 years ago

  • Status changed from Feedback to Open

Paolo Cavallini wrote:

Wouldn't it be better to redirect to a page "docs missing - please write your and send it to ..."?

This recalls me one of my first PRs to QGIS and i've been answered that "when someone is looking for a doc, most of the times it's because he does not know how that works. So hard to ask him to write the docs." :) It was not false!
That said, there's another report about improving returned message at #17666 (to help user find out what makes the link fail)

The issue I'm trying to raise here is that hitting most of the help button from algorithms dialog leads to no doc. Link construction in application and documentation do not match. From what i can see, changes have been made meanwhile but it does not fix the issue. We still need to handle use of "_" character in links (generated by Sphinx in case of spacing in file name (ie group) - which we need to properly show readable and translatable page title) and use of "-" character (in case of spacing in algorithmn name)
Example:
https://docs.qgis.org/testing/en/docs/user_manual/processing_algs/qgis/raster_terrain_analysis.html#ruggedness-index (from docs) vs https://docs.qgis.org/testing/en/docs/user_manual/processing_algs/qgis/rasterterrainanalysis.html#ruggednessindex (from QGIS)
https://docs.qgis.org/testing/en/docs/user_manual/processing_algs/qgis/layer_tools.html#extract-layer-extent (from Docs) vs https://docs.qgis.org/testing/en/docs/user_manual/processing_algs/qgis/layertools.html#polygonfromlayerextent (from QGIS - here, even the name does not match the name nor the dialog title shown in QGIS)

#13 Updated by Nyall Dawson about 2 years ago

  • Status changed from Open to Closed
  • % Done changed from 0 to 100

#14 Updated by Giovanni Manghi about 2 years ago

  • Resolution set to fixed/implemented

Also available in: Atom PDF