Open Stack

Good news everyone.

Our translators have been going gang-busters, and we have a complete 
Japanese install guide (Korean and German are both past half-way). 
Inspired by this, with Daisy and Andreas, I've been playing with the 
build jobs to get these online.

Here's how it all works:

1. Whenever we make a change in the English document, after the patch 
merges*, these changes** are uploaded to Transifex so translators can 
get to work on them straight away.

2. Periodically***, the latest changes are downloaded from Transifex and 
submitted in the form of a gerrit review - amending the appropriate 
language file(s) in the locale directory of the documents being 
translated - for us to approve when we think is appropriate

3. As another job after patches merge, the downloaded translations are 
used to feed a maven build of languages as specified****, making them 
available at docs.openstack.org/{lang}/{doc}/content.


You can see a successful example of the entire chain here:

http://docs.openstack.org/ja/trunk/openstack-ops/content/



However:
* Step 2 is currently completely broken
* Only Japanese is generated for only the operations guide, and no other 
documents are set up to be published


and this is where I've been playing.

==> The first step was to fix our case that should have been working all 
along: openstack-operations-guide-ja. The fix here was relatively 
simple: https://review.openstack.org/#/c/66998/

==> We also isolated why step 2 is broken. The 
manuals-propose-translation-update job modifies .tx/config with bad 
values, leading to unmerged changes in the git commit, which causes 
git-review to fail.

==> I've just submitted a new patch, which will make the existing 
Japanese ops guide build job generic, and created a new generic 
"language" job for the install guide. In this way, we can control which 
languages we want to build by specifying the line in layout.yaml. Since 
the install guide Japanese version is 100% done, I've proposed to add it 
in the same patch, so it can be made available at 
http://docs.openstack.org/ja
https://review.openstack.org/#/c/67481/

==> There is also a final issue that, while not pressing, should be 
addressed shortly: use of openstack-doc-tools instead of tools directory 
in repositories



Regards,


Tom

* To be technical, a zuul "post" job
** In the form of a PoT file, created by tools/generatepot
*** Probably at 6AM every day, UTC, and only if there have been any changes
**** Using tools/generatedocbook