The OpenStack documentation team has validated the manuals in the openstack-manuals repository using a python tool. We now have moved this and other tools into a new openstack-doc-tools repository. The goal is to have a single place for the tools that are needed for different documentation repositories.
During the last weeks, I expanded the tools so that they handle also the API project repositories like api-sites and volume-api (the published versions are found via http://api.openstack.org/). The tools found many problems in the current API projects, including some projects that did not even built. The errors found by these are a clear sign that we do need these gating jobs. Diane Fleming and myself fixed the problems that the validation tool found. A small number of problems are still being worked on but all repositories build again and are setup for using the new gates.
Since yesterday, the api-sites repository uses this new tool for gating!
Validating your changes
If you like to run the gates locally: Install the python tox package and run 'tox' from the top-level directory to use the same tests that are done as part of our Jenkins gating jobs. If you like to run individual tests, run:
'tox -e checkniceness' - to run the niceness tests
'tox -e checksyntax' - to run syntax checks
'tox -e checkdeletions' - to check that no deleted files are referenced
'tox -e checkbuild' - to actually build the manual(s)
Note that these checks only test the files of the most recent commit, so first 'git commit' everything, then run 'tox'. To check all files, pass '--force' as parameter to the tox command, for example 'tox -e checkniceness -- --force'. The '--' is important, it passes the option down to the validation tool.
Note that the tools need the maven package as requirement, so install that one as well.
Repositories gating
As a first step, api-sites is gating now with these four checks. The niceness check is optional (non-voting). The other api projects (compute-api, database-api, identity-api, image-api, netconn-api, object-api, and volume-api) will soon be setup as well for this.
Additionally, these gates will replace the existing gates for the openstack-manual and operations-guide repositories. Once this is done via have for all repositories the same setup and just a single repository with all the validation tools.
openstack-doc-tools repository
The repository can be downloaded as a Python package from pypi and currently contains tools for:
validation/gating: as explained above
translated documents: Tom Fifieldt is looking on enhancing and using these now.
Autogeneration of tables: Shaun McCance is enhancing these to nicely generate configuration tables of options specified in the various conf files like nova.conf.
cleanup tools: Those can be used to remove some whitespace.
Help in improving the tools is always welcome. If you have questions, join the documentation team on the #openstack-doc IRC channel or on the openstack-docs mailing list
Thanks
Thanks especially to Fungi and Clark for guidance and review on how to do this in the best way, to Diane for fixing many problems, for Tom, Anne and others for reviews and comments!