2.3 KiB
Config Reference: document common options
https://blueprints.launchpad.net/openstack-manuals/+spec/config-ref-common-sections
Problem description
In the configuration reference, configuration options such as database, AMQP, keystone middleware are poorly documented, or worse, documented differently in multiple places.
This might be confusing for the reader, and adds maintenance burden.
Proposed change
Common libraries define several configuration options, used by all the OpenStack projects. Instead of documenting these options for each project, we could have a specific chapter documenting the configuration options for common libraries, and refer to this chapter in the projects chapters.
At the moment these options are poorly documented, so this change would also be a chance to add missing information, or at least provide a better structure to do so in the future.
This spec only impacts the configuration reference.
Alternatives
- Document everything in all the projects chapters, leading to a lot of duplication
Implementation
Assignee(s)
Primary assignee: gpocentek
Work Items
- Generate options tables using
autohelp
for the common libraries. The options would not be removed from the projects tables, to keep providing a complete set of options for each project. - Add a new
Common configuration options
chapter to the configuration reference, documenting configuration options available inoslo
andkeystonemiddleware
libraries. Documented libraries include (non-exhaustive list):oslo.concurrency
oslo.db
oslo.log
oslo.messaging
keystonemiddleware.auth_token
- Remove documentation for these options in the projects chapters, if
necessary (AMQP with
oslo.messaging
is sometimes documented). - In each component chapter, add references to the common options sections.
Dependencies
None
Testing
- Validate the existence of documented options using the tables
generated with
autohelp
.
References
None