Blueprint-autogenerate-config-tables

Launchpad Entry: autogenerate-config-tables
Created: Tom Fifield
Contributors:

Summary

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.

Rationale

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.

Design

The system:

'parses' the code of {nova, swift, quantum, cinder, glance, keystone} to determine current configuration options, default values and help text
outputs docbook table format as below
creates/updates a file with the options from the table
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%"/>
     <thead>
         <tr>
             <td><para>Configuration option=Default value</para></td>
             <td><para>(Type) Description</para></td>
         </tr>
     </thead>
     <tbody>
         <tr>
             <td><para> option_name=default_value </para></td>
             <td><para> (TypeOpt) Description text goes here</para></td>
         </tr>
         ... 
         more table rows here
          ...
           </tbody>
 </table>
 </para>

Issues

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