[Qgis-community-team] Report of QGIS documentation meeting

[Richard Duivenvoorde]

On 23/03/2019 23.02, Richard Duivenvoorde wrote:
>> Maybe do I misunderstand the point 4 but isn't it already the case (at
>> least from a goal perspective - for technical details I don't know)?
>> Common images (icons) as well as screenshots are available in source
>> file preview in github [0]
>> See also [1] [2] for the implementation details.

> Yep, that works, because we do copying/rsyncing of
> https://github.com/qgis/QGIS-Documentation/tree/master/static
> (needed for git*.com)
> to
> https://github.com/qgis/QGIS-Documentation/tree/master/source
> (needed for Sphinx)
> during build.

(sorry for all these emails, I hope somebody can still follow...)

Ah, duh. Found another 'solution' for this!

So the actual problem is that the Sphinx build process and the git*.com
renderers have a different notion what '/static' means. And that is ONLY
because we have the static and conf.py in a separate /source folder...
So we can also just remove the source folder! Which is actually an
option when you create a fresh sphinx project!
See the 'nosourcedir' branch:
https://github.com/rduivenvoorde/qgisdoc/blob/nosourcedir/docs/user_manual/trans.rst

For clarity: this has only to do with the place of the static folder: if
we do it like above we do not need to copy/sync that folder anymore
during build. AND the question about using relative paths is just not
relevant anymore (because /static/common then works in build and online).

In the same branch I've experimented with moving the substitutions back
to conf.py or try to include the substitutions directly in the rst files.
But that just is still not working for both git*.com renderers.... (as
Alexandre found out some time ago)

For the inline substitutions to work we have 2 options:
1) use current master scenario: a script finds all substitution keys
from rst files, and adds them based on substitutions.txt to the rst
files bottom, so the git*.com renderers have them at hand and can show them.
2) declare every 'common' image 'substitution' again in the rst file it
is being used

But probably 1 is ok for now?

Regards,

Richard