Oct 8, 2013

Improving the OpenStack Documentation Build Tools

During the last weeks, the tool for building and checking the OpenStack Documentation manuals has been improved.

Now we have one new tool with a few different options for fine-grained control. It is run as part of the gates and can be run locally as well. If you used tools/validate.py to test your changes locally, you should now use tools/test.py.
Instead, of a single gate job, there are now four checking gates, you'll see now something like the following from Jenkins:

The advantage of all of these changes are that a writer submitting a patch gets quickly an overview about what fails. This is due to the separate jobs. These jobs only check what has changed and thus do not build all books but only those impacted by the change under review.

Description of Checks

Note that all checks parse the git output to record the modified files in a review and only look at these files. If you want to run checks locally on all files, use the --force option.

Niceness check

This tests for extra whitespace. It is non-voting for now and thus not run as part of the final gate.

Syntax check

Deletions check

This check tests whether any files have been removed and if those are still referenced anywhere. It handles images and include files.

Build Check

This check will build all books that might be modified by the commit. It checks which files are modified and which books include these files and runs a check of all books where one file was changed. The books are build in parallel to speed up building.

For the Install Guide, it builds all three variants of the Guide - the Fedora/RHEL/Centos Install Guide, the Ubuntu Install Guide and the openSUSE Install Guide.
It now also builds the High Availability Guide (which is not using DocBook but asciidoc) if one of its files has changed.Thus, everything is build the same way as we do for publishing the manuals to the OpenStack docs site.

Since we only build the modified books and build them in parallel, you might get now a comment from Jenkins in a minute or two while you had to work 30 minutes in August for this. Jenkins currently needs around 10 minutes to build all books.