[QGIS-Developer] QGIS Doc Travis

[Richard Duivenvoorde]

On 3/15/20 8:57 AM, matteo wrote:
> That's what comes into my mind:
> 
> * verify Transifex pulling/pushing
> * apache on the server to publish the docs
> * ... what else?

@Raymond thanks for organising the hackfest! Sorry for not being
there... But the 'doc-team' did some things related to documentations
because there WAS a hackfest \o/

There are 2 things I want to discuss here.

First our main goal: "KISS".
Everybody on windows or linux should be able to build at least the
english docs.

Second: stick to Sphinx and it's tools as much as possible (e.g. instead
of custom scripts: use sphinx-intl to create transifex stuff).

My main 2 questions, I would like to discuss:

-1- CAN we use Travis to build the translated site (daily) (technically:
yes, I know, but...)

-2- WHICH process should be responsible for the pulling of the transifex
translations into the build process

Ad -1-
"Make doctest" will use the qgis/qgis docker container to build and run
the tests. Travis is happy with that [4]

So we could update or base a new image on it containing all language
related stuff, and use travis to build all languages. Current 3.4 builds
pull fresh from transifex (making a language build lasts for half an
hour now sometimes...) If we push the po files into github, it will only
be 10 minutes.
But my main question is: can/should we 'misuse' travis to build all
those (currently 18) languages daily.

Ad -2-
Several options:
- during our main build, the build pulls (tx pull) from transifex. Is
what we do now: Transifex is main repo for translations. IF an
individual wants to build a translated doc, she/he needs to pull the
translations from transifex itself (which is a disadvantage, as pulling
translations from tx is SLOW...)
- we run a daily script which pulls the translations from tx and commits
those po files (for ALL languages to be build) in git-repo.
Main advantage: we keep being boss over the po files ourselves, AND
everybody can build translated docs, because the po files are (well 1
day old...) in git
- use the Transifex Github integration (I played with it one year ago,
and then it could not handle our long resource handles at that time...)

I think I prefer the second or third option, will push nl, it and fr
translations into git later today (by just pulling the 3.4 translations
from build server), so everybody can try to build translated sites too.
Als together with maybe building it on travis, it is probably the best
way..

Want to see current status?

- vanilla Sphinx local ( EVERYBODY can try to build branch qgisdoc2020
NOW on windows and linux, see README [0] )

- vanilla Sphinx remote ('make site' works if you can like me rsync to
qgis2 [1]) (NOTE: a lot has to be done there....)

- everybody should now be able to 'just edit' on github [2]

- 'make doctest' (== building in te qgis/qgis docker image) is also
working, see travis [4] qgisdoc2020 branch there


Sorry for being rather long, and while writing maybe answering my own
questions :-)

But I really really hope we can keep stuff as simple as possible and
encourage everybody to JOIN. Please contact us via documentation list

About PDF's: maybe later... but I'm OK without those...
So if you want them: join us

Regards,

Richard Duivenvoorde


[0] https://github.com/qgis/QGIS-Documentation/tree/qgisdoc2020
[1] https://docs.qgis.org/3.10/
[3]
https://github.com/qgis/QGIS-Documentation/blob/qgisdoc2020/docs/user_manual/introduction/getting_started.rst
[4] https://travis-ci.org/github/qgis/QGIS-Documentation
[5] https://docs.transifex.com/transifex-github-integrations/github-tx-ui