[Qgis-community-team] Doc images and github

[Richard Duivenvoorde]

Hi, as promised I started to move around images in our docs source (only
ONE rst file for now)

Eg, the dialog screendumps from

https://github.com/qgis/QGIS-Documentation/blob/master/source/docs/user_manual/working_with_vector/vector_properties.rst

are now in a local 'images'-directory next to rest. So the :figure:
directives have a relative path to the image in the 'images'-dir.
Meaning that in the link above the screendumps are shown in Github.

I also removed all little |nix| icon substitutions.
And I removed the :menuselection: and :guilabel: thingies.

One thing I want to discuss is what to do with the (little) inline
images we have, like the button-images showing up in text.
In rst you can ONLY do inline images apparently by creating
substitutions for them. So there is no other way then to create a
substitution part for these.

BUT there are two options here:
-1- define them in a central place (like now: conf.py): nice because you
define them only once (theoretically) and no doublures in images, but...
NOT nice: Github is not able to resolve those in conf.py defined
substitutions
-2- define them locally in the rst file where you use them. This has as
drawback that very often used inline images (like the checkbox) are
defined + image copied very often.
BUT the nice thing about it is that IF you define them in the rst file,
Github is able to resolve those SO they show up as inline images their.

To see the difference, compare:

https://github.com/qgis/QGIS-Documentation/blob/master/source/docs/user_manual/working_with_vector/vector_properties.rst#labels-menu

with

https://github.com/qgis/QGIS-Documentation/blob/master_github_e/source/docs/user_manual/working_with_vector/vector_properties.rst#labels-menu

as you can see in the last one I moved (only) the checkbox substitutions
to the rst file and those little checkbox images show up nicely in the
text (compared to the other link where you see |checkbox| everywhere in
the text. IF we move all substitutions in a rst file from the conf.py to
the rst file itself, all the |xxxx| will show nice inline images.

I also tried a compromise between those two: I move the images to the
static/common folder before build already, and tried to use relative(!)
url's in , but that fails, because apparently the root for those path's
is NOT the position of conf.py, but the place where you USE the
substitution. Meaning we cannot reuse a substitution anymore, and the
whole re-use arguement is useless. NOTE that currently we used non
relative path like /static/common/... !

If anybody has better insight, please let us know.

Else: what your preference from the two options above?
I tend to want to see those images in github, making it easier to
read/edit directly there (so option 2). The drawback of duplicates of
subs and images I take for grantage.

So doc-writers, please raise your hand for one of the options (well.. I
hope it is clear enough to make a choice ....)

Regards,

Richard Duivenvoorde