QGIS » QGIS Application

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

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.

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.

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

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?

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?

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

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.

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

Proposed PR at https://github.com/qgis/QGIS/pull/6298