[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, <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
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.osgeo.org/pipermail/qgis-community-team/attachments/20171223/df54a82a/attachment-0001.html>