Jump to: navigation, search

Difference between revisions of "Blueprint-evolution-of-autogenerate-config-docs"

(Using generator.py from oslo-incubator)
 
(12 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 
* '''Launchpad Entry''':  [https://blueprints.launchpad.net/openstack-manuals/+spec/evolution-of-autogenerate-config-docs Evolve autogenerate tools]
 
* '''Launchpad Entry''':  [https://blueprints.launchpad.net/openstack-manuals/+spec/evolution-of-autogenerate-config-docs Evolve autogenerate tools]
 
* '''Created''': Andreas Jaeger
 
* '''Created''': Andreas Jaeger
* '''Contributors''':  
+
* '''Contributors''': Tom Fifield
 
* '''Planned implementation release''': Icehouse
 
* '''Planned implementation release''': Icehouse
  
Line 15: Line 15:
 
* We need to be able to show the same option in different tables for shared options
 
* We need to be able to show the same option in different tables for shared options
 
* Options with the same name - but specified in different tables - will show up as duplicated entries in a table.
 
* Options with the same name - but specified in different tables - will show up as duplicated entries in a table.
 +
* Relies on a global CONF object to be loaded on module import
 +
* Needs installation of many dependencies to work
 +
* The filename of the file is used as part of the caption for the generated table, this should be configurable
 +
* Imports details of machine it runs on into the tables. Noticed so far: hostname, IP address, location of python libs
 +
* Does not handle whitespace properly. For example instance_format is defined as '[instance: %(uuid)s] ' (whitespace at end) and shows up in the sample conf files as: instance_format="[instance: %(uuid)s] " but we do not show the extra whitespace in the table
 +
* Not all flags are extracted
  
 
=== Using generator.py from oslo-incubator ===
 
=== Using generator.py from oslo-incubator ===
Line 24: Line 30:
 
=== New format for generated tables ===
 
=== New format for generated tables ===
  
The tables should additionally contain the section, for example <code>[DEFAULT]</code>
+
The generated tables should additionally contain the section, for example <code>[DEFAULT]</code> and the filename, for example <code>nova.conf</code>.
  
 
== Related bug reports ==
 
== Related bug reports ==
  
 
* [https://bugs.launchpad.net/openstack-manuals/+bug/1226464 Duplicates in generated tables]
 
* [https://bugs.launchpad.net/openstack-manuals/+bug/1226464 Duplicates in generated tables]
 +
* [https://bugs.launchpad.net/openstack-manuals/+bug/1240804 autohelp tool does not extract vmware flags in cinder]
 +
 +
----
 +
[[Category:Documentation Blueprint]]

Latest revision as of 09:53, 2 February 2014

  • Launchpad Entry: Evolve autogenerate tools
  • Created: Andreas Jaeger
  • Contributors: Tom Fifield
  • Planned implementation release: Icehouse

Overview

The current autogenerate tools have a couple of limitations and we need to improve the tool to handle all current uses in the manuals. We should also evaluate switching to generator.py from oslo-incubator - and enhancing that tool.

Blueprint

Current limitations and problems

  • The configuration file names, and sections within them are not shown at all
  • We need to be able to show the same option in different tables for shared options
  • Options with the same name - but specified in different tables - will show up as duplicated entries in a table.
  • Relies on a global CONF object to be loaded on module import
  • Needs installation of many dependencies to work
  • The filename of the file is used as part of the caption for the generated table, this should be configurable
  • Imports details of machine it runs on into the tables. Noticed so far: hostname, IP address, location of python libs
  • Does not handle whitespace properly. For example instance_format is defined as '[instance: %(uuid)s] ' (whitespace at end) and shows up in the sample conf files as: instance_format="[instance: %(uuid)s] " but we do not show the extra whitespace in the table
  • Not all flags are extracted

Using generator.py from oslo-incubator

generator.py currently handles the parsing of config options and writing of "*.conf" files, like "nova.conf" as shipped as samples in the OpenStack code repositories. Instead of writing our own tool and handling some exceptions, I propose to enhance generator.py so that it writes the tables for us.

For this we need to figure out where our config files should life.

New format for generated tables

The generated tables should additionally contain the section, for example [DEFAULT] and the filename, for example nova.conf.

Related bug reports