[Qgis-community-team] Doc images and github

[Alexandre Neto]

Not an easy choice... I'm not very fond of duplicating substitutions images
as I believe it will lead to pages with different icons because someone
just update one place. Maybe it would be possible to have a common place
with all  images and some kind of script to copy the icons to a child
forder near the rst?

Is a third option valid? Since we (you) are making some experiments, how
about put all rst files in the same folder? For document I mean. What is
the impact on the documents? This would made possible to have a single
place for the substitutions?

Alexandre

Richard Duivenvoorde <richard at duif.net> escreveu no dia domingo, 24/01/2016
às 20:59:

> 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
> _______________________________________________
> Qgis-community-team mailing list for organizing community resources such
> as documentation, translation etc..
> Qgis-community-team at lists.osgeo.org
> http://lists.osgeo.org/mailman/listinfo/qgis-community-team

-- 
Alexandre Neto
---------------------
@AlexNetoGeo
http://sigsemgrilhetaswordpress.com
http://gisunchained.wordpress.com
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.osgeo.org/pipermail/qgis-community-team/attachments/20160125/b20cb062/attachment.html>