[Qgis-community-team] Figures internationalization and inline substitutions for QGIS3

[delazj at gmail.com]

Hi Alexandre,

Comments are a bit late given that the pull request is already published (i wrote them few days ago) but i have some requests that may be of interest for coding skills people that would like to help in documentation in 2018 (one of my QGIS wishes for 2018) so i'm answering here for the wider audience.
My opinion inline... 

Le 23 déc. 2017 6:48 PM, Alexandre Neto <senhor.neto at gmail.com> a écrit :
>
> Sorry, maybe I was not clear, and my example didn't help.
>
> My proposal is not to duplicate the icons' png files. They would be all in the same "static" folder inside the "source" folder. But, for each rst file, we would need to add the necessary substitutions at the bottom to have github preview.

No problem. This is what i understood. And i'm globally fine with that.

> (in my example, out of laziness, I have copied all the confusion.py substitution, but most rst only have a handful of them) 
> We also need to use relative paths, but that's not that bad because the relative path is always the same, as the rst files (excluding the indexes) are always at the same distance of the static folder.

Indeed you are right. I was afraid we had to check paths for this kind of section move but it's not an issue. Only Processing algorithms chapter has subfolders and it's somehow a self-contained chapter (with few substitutions at the moment) so it'd be ok.

--------
What would be very nice is to have this scripted, a kind of code that will scan each commit/rst file and append the rst file with the |xxx| found in the file (except |updatedisclaimer| which i think is the single intruse here) + necessary settings (width eg). It could ease the transition to this new structuring (but it looks like you already did it manually?) and later, run as a pre commit hook or just a command to fix used substitution list quicker. 

Am i the only one finding it potentially useful? If not, any skilled member to take the lead?
More generally i think there are cases we'd need scripts in doc repo management, eg when a new branch is created, clean properly all |updatedisclaimer| at the top of the pages, renaming stable branch and history... ie those redundant, boring but necessary things to do
--------

Back to your request, it's a YES from me (in case it wasn't clear until now).
I'll comment the pull-request later. 

Regards, 
Harrissou

> Anyway, I have tested, and there's seems to be no other way... Sorry.
>
>
> A sáb, 23/12/2017, 16:50, <delazj at gmail.com> escreveu:
>>
>> Hi Alexandre,
>>
>> Thanks for your efforts. I later saw your yesterday chat with Richard (sorry!) and it looks like things has progressed since... 
>> Being able to see the docs without having built it will likely make docs writing and review more comfortable. This could really help eg to review many of the Processing help pull requests that are awaiting for reviewers for weeks (reader, in case you wonder, this was a call for people to review the new description files of our beloved algorithms - just comment if it's right and makes sense to you, it's in good english and complete enough). 
>> If it could then attract more writers, Bingo...
>>
>> About the icons/text replacement, i think duplication is a no-go: a single place to list them all and UPDATE them when they change; tracking those occurences will be a nightmare (yes, i like exageration!!!). 
>> But do you mean that we would need to list in each rst file the substitutions we used in it (with relative paths)? Png files would all be at the single place but reference to each of them will be recreated in each file they are used? Tracking won't be easier, neither (+ relative paths errors/failures when section moves). I'm not sure this really eases the writing process. There's no way to just mention them like we do now? Any other github/sphinx guru around to help for the missing gaps/bits? I just discover the :class: role so cannot be of any help.
>>
>> Honestly, in case i well understood the proposal, i'm balanced because of the replacement management. 
>> Keen to hear others' opinion... 
>> And again, thanks for tackling this. Would be a nice feature for docs team :-)
>>
>> Regards, 
>> Harrissou
>>
>> Le 22 déc. 2017 23:49, Alexandre Neto <senhor.neto at gmail.com> a écrit :
>>>
>>> Hi all,
>>>
>>> I have been fiddling with QGIS documentation trying to go back to Richrd objective of seeing the figures and inline image substitutions on github markdown preview. I think I made it! But we may need to do some changes, so I would like to discuss that with you.
>>>
>>> For Figure preview on github we arlready knew what needed to be done. We need to move the images to a folder above the rst file in a "image" or "img" folder. But we had the problem with internationalization of the images. I found out that all we need to do is add this line to the conf.py file:
>>>
>>> figure_language_filename = '{path}{language}/{basename}{ext}'
>>>
>>> And then, put any language specific figure, with the exact same name as the english version inside a images/[language_code] folder.
>>> When building a different language, sphinx will look into those folders and if an equal filename exists, replaces the "english" figure.
>>>
>>> This even allow us to clean up all that mumbo jumbo of copying the resourses forlder according to the language to a temporary static folder
>>>
>>> For inline substitutions to be previewed in github, I found out that we need to put the substitution command inside the rst file itself (instead of added by conf.py as a rst_epilog), we need to be able to set a relative path from the rst to the image, and  and we need set the class as inline. but we all need to have the image available from github.
>>>
>>> So, either we put the necessary icons files in each "image/common" folder as needed (which may lead to duplicates), and the substitution would look like this:
>>>
>>> .. |add| image:: /static/common/mActionAdd.png
>>>    :class: inline
>>>    :width: 1.5em
>>>
>>> or we put them all together in a static folder in source, and we set relative paths from the rst file, like this:
>>>
>>> .. |add| image:: ../../../static/common/mActionAdd.png
>>>    :class: inline
>>>    :width: 1.5em
>>>
>>> I would prefer the second option.
>>>
>>> Here's an example of this kind of working:
>>>
>>> https://github.com/SrNetoChan/QGIS-Documentation/blob/test_inline/source/docs/user_manual/introduction/qgis_gui.rst
>>>
>>> you will notice that there is a image folder, and inside a PT_pt folder.
>>>
>>> Let me know what you think before I start creating a pull request to change all images the conf.py and the makefile.
>>>
>>> Thanks!
>>> -- 
>>> Alexandre Neto
>>> ---------------------
>>> @AlexNetoGeo
>>> http://sigsemgrilhetas.wordpress.com
>>> http://gisunchained.wordpress.com
>
> -- 
> Alexandre Neto
> ---------------------
> @AlexNetoGeo
> http://sigsemgrilhetas.wordpress.com
> http://gisunchained.wordpress.com