Jump to: navigation, search



Develop a system to automatically create configuration option tables based on the code, and keep them up to date.

This will ensure the configuration option references are always correct and reduce effort required by the limited members of the documentation team.


Currently, tables of configuration options in the manuals are written and updated manually. This results in:

  • delay updating configuration options
  • incorrect updates due to the manual nature
  • inefficient use of time, as most cases these are verbatim from the code.


The system:

  1. 'parses' the code of {nova, swift, quantum, cinder, glance, keystone} to determine current configuration options, default values and help text
  2. outputs docbook table format as below
  3. creates/updates a file with the options from the table
  4. sends a review in to Gerrit with the changed file(s)

File format

 <?xml version="1.0" encoding="UTF-8"?>
 <para xmlns= "http://docbook.org/ns/docbook" version= "5.0"> 
  <table rules= "all">
     <caption>Description of nova.conf file configuration options
         for sectiopn</caption>
     <col width= "50%"/>
     <col width= "50%"/>
             <td><para>Configuration option=Default value</para></td>
             <td><para>(Type) Description</para></td>
             <td><para> option_name=default_value </para></td>
             <td><para> (TypeOpt) Description text goes here</para></td>
         more table rows here


  • Documentation updates of configuration tables will get overridden
    • Documentation changes to textual descriptions for configuration variables should then be made in the respective code project, which also improves the quality of the CLI descriptions.
  • The way configuration options are split in the code is different to how they are split in the books
  • Configuration options in the code don't necessarily match those in the sample config files
  • Default values aren't always in the option declaration, and can be found later in the code