Difference between revisions of "Blueprint-autogenerate-config-tables"
| (2 intermediate revisions by the same user not shown) | |||
| Line 2: | Line 2: | ||
* '''Launchpad Entry''': [https://blueprints.launchpad.net/openstack-manuals/+spec/autogenerate-config-tables autogenerate-config-tables] | * '''Launchpad Entry''': [https://blueprints.launchpad.net/openstack-manuals/+spec/autogenerate-config-tables autogenerate-config-tables] | ||
* '''Created''': Tom Fifield | * '''Created''': Tom Fifield | ||
| − | * '''Contributors''': | + | * '''Contributors''': Steven Deaton |
== Summary == | == Summary == | ||
| Line 22: | Line 22: | ||
# sends a review in to Gerrit with the changed file(s) | # sends a review in to Gerrit with the changed file(s) | ||
| + | ===File format=== | ||
<pre> | <pre> | ||
<?xml version="1.0" encoding="UTF-8"?> | <?xml version="1.0" encoding="UTF-8"?> | ||
| Line 48: | Line 49: | ||
</para> | </para> | ||
</pre> | </pre> | ||
| − | + | ||
== Issues == | == Issues == | ||
* Documentation updates of configuration tables will get overridden | * Documentation updates of configuration tables will get overridden | ||
| Line 54: | Line 55: | ||
* The way configuration options are split in the code is different to how they are split in the books | * 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 | * 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 | ||
---- | ---- | ||
[[Category:Spec]] | [[Category:Spec]] | ||
Latest revision as of 05:09, 14 May 2013
- Launchpad Entry: autogenerate-config-tables
- Created: Tom Fifield
- Contributors: Steven Deaton
Contents
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
