Processing help system expects wrong link

[qgib]

Author Name: Harrissou Santanna (@DelazJ)
Original Redmine Issue: 17231
Affected QGIS version: master
Redmine category:processing/core
Assignee: Victor Olaya

---

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'

[qgib]

Author Name: Alexander Bruy (@alexbruy)

---

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.

---

• status_id was changed from Open to Feedback

[qgib]

Author Name: Harrissou Santanna (@DelazJ)

---

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....)

[qgib]

Author Name: Alexander Bruy (@alexbruy)

---

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:

• QGIS algorithm have URL which follows the way algorithms grouped in QGIS (provider - group - algorithm) but still relies on the translatable strings and invalid provider name: http://docs.qgis.org/testing/en/docs/user_manual/processing_algs/qgis/vector_geometry_tools.html#explode-lines
• On other hand GDAL algorithm does not follow same structure. There is no group called "GDAL Conversion" under GDAL algorithms. There is a group called "Conversion" but in the URL group name prepended with some text:
  http://docs.qgis.org/testing/en/docs/user_manual/processing_algs/gdalogr/gdal_conversion.html#pct-to-rgb
  Also it relies on the translatable strings and invalid provider name like previous link.

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.

[qgib]

Author Name: Harrissou Santanna (@DelazJ)

---

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.

[qgib]

Author Name: Alexander Bruy (@alexbruy)

---

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

[qgib]

Author Name: Harrissou Santanna (@DelazJ)

---

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?

[qgib]

Author Name: Alexander Bruy (@alexbruy)

---

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?

[qgib]

Author Name: Harrissou Santanna (@DelazJ)

---

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...

[qgib]

Author Name: matteo ghetta (@ghtmtt)

---

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.

[qgib]

Author Name: Paolo Cavallini (@pcav)

---

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

[qgib]

Author Name: Harrissou Santanna (@DelazJ)

---

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 #25563 (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)

---

• status_id was changed from Feedback to Open

[qgib]

Author Name: Nyall Dawson (@nyalldawson)

---

Proposed PR at #6298

[qgib]

Author Name: Nyall Dawson (@nyalldawson)

---

Applied in changeset 2d1e918.

---

• status_id was changed from Open to Closed
• done_ratio was changed from 0 to 100

[qgib]

Author Name: Giovanni Manghi (@gioman)

---

• resolution was changed from to fixed/implemented