[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://sigsemgrilhetas.wordpress.com
http://gisunchained.wordpress.com
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.osgeo.org/pipermail/qgis-community-team/attachments/20171222/18526e5a/attachment.html>