dea0e970d1
As discussed on the mailing list, this patch will make the swift configuration tables found in common a source of truth for the helptext. The script that generates them has been updated for this, and will now only add/remove options, update default values, and replace helptext where it does not exist in the tables. Another run of the script was done and tables were updated. Backstory: All projects other than Swift use OpenStack Common for configuration, and define option, default value and help text in the code in a way that it's possible to extract. Since the code is able to act in this way, we can stop maintaining separate instructive lines for configuration options, and instead fix any text problems in the code itself. This both improves the quality of the code and fixes our double maintenance problem. For swift, we needed a different approach. Unfortunately, I think we don't have the ability to treat the code as the definitive source and move all maintenance there. The lack of instruction for every option, and absence of structure precludes this. So I wrote some nasty scraping things (from RST and sample conf file) to seed an initial list of configuration options. My plan from here was to make the 'update' portion of the script treat the textual descriptions in common/tables/swift-*.xml as definitive. The script would still search the swift code to add or remove options, so we could guarantee completeness, and after an initial push to write out proper help text the maintenance becomes far simpler. Change-Id: I2464f5c63cb0da110e1871a09a59380dad9b6b27
autogenerate-config-docs
Automatically generate configuration tables to document OpenStack.
Dependencies: python-git (version: 0.3.2 RC1), oslo.config
Setting up your environment
Note: This tool is best run in a fresh VM environment, as running it requires installing the dependencies of the particular OpenStack product you are working with. Installing all of that on your normal machine could leave you with a bunch of cruft!
First install git and python-pip,
$ sudo apt-get install git python-pip
next, install oslo.config and GitPython
$ sudo pip install oslo.config GitPython
then, checkout the repository you are working with:
$ git clone https://github.com/openstack/nova.git
(this guide makes reference to a /repos directory, so you should record the directory you are using and replace as appropriate below)
and the tool itself:
$ git clone https://github.com/openstack/openstack-manuals.git
and finally, the dependencies for the product you are working with:
$ sudo pip install -r nova/requirements.txt
Now you are ready to use the tool.
Using the tool
This tool is divided into three parts:
-
Extraction of flags names eg
$ ./autohelp.py --action create -i flagmappings/nova.flagmappings -o names --path /repos/nova
-
Grouping of flags
This is currently done manually, by using the flag name file and placing a category after a space.
eg
$ head flagmappings/glance.flagmappings
admin\_password registry
admin\_role api
admin\_tenant\_name registry
admin\_user registry
...
- Creation of docbook-formatted configuration table files
eg
$ ./autohelp.py --action create -i flagmappings/nova.flagmappings -o docbook --path /repos/nova
A worked example - updating the docs for H2
update automatically generated tables - from scratch
$ sudo apt-get update
$ sudo apt-get install git python-pip python-dev
$ sudo pip install git-review GitPython
$ git clone git://github.com/openstack/openstack-manuals.git
$ cd openstack-manuals/
$ git review -d 35726
$ cd tools/autogenerate-config-docs/
Now, cloning and installing requirements for nova, glance, quantum
$ for i in nova glance quantum; do git clone git://github.com/openstack/$i.git; done
$ for i in nova glance quantum; do sudo pip install -r $i/requirements.txt; done
This missed some requirements for nova, which were fixed by:
$ sudo pip install python-glanceclient websockify pyasn1 python-cinderclient error_util
$ sudo apt-get install python-ldap python-lxml
Making the flag names update
./autohelp.py -vvv --action update -i flagmappings/nova.flagmappings -o names --path ~/nova | more
At this point, seach through flagmappings/nova.flagmappings.new for anything labelled Unknown and fix, once that is done use:
./autohelp.py -vvv --action create -i flagmappings/nova.flagmappings -o docbook --path ~/nova
to generate the XML files and move those into the appropriate part ofthe git repo