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

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
3 messages Options
Reply | Threaded
Open this post in threaded view
|

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

Alexandre Neto
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://gisunchained.wordpress.com

_______________________________________________
Qgis-community-team mailing list for organizing community resources such as documentation, translation etc..
[hidden email]
https://lists.osgeo.org/mailman/listinfo/qgis-community-team
Reply | Threaded
Open this post in threaded view
|

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

DelazJ

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 <[hidden email]> 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://gisunchained.wordpress.com

_______________________________________________
Qgis-community-team mailing list for organizing community resources such as documentation, translation etc..
[hidden email]
https://lists.osgeo.org/mailman/listinfo/qgis-community-team
Reply | Threaded
Open this post in threaded view
|

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

Alexandre Neto

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.
(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. Anyway, I have tested, and there's seems to be no other way... Sorry.


A sáb, 23/12/2017, 16:50, <[hidden email]> 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 <[hidden email]> 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://gisunchained.wordpress.com
--
Alexandre Neto
---------------------
@AlexNetoGeo
http://gisunchained.wordpress.com

_______________________________________________
Qgis-community-team mailing list for organizing community resources such as documentation, translation etc..
[hidden email]
https://lists.osgeo.org/mailman/listinfo/qgis-community-team