Automatically Generated Project

Documentation

Improvements to Oslo Tools During Mitaka

Doug Hellmann

April 2016

oslo.config

Sample Config Generator

  • plain text output

  • options, help text, groups, etc.

  • application control option ordering

[DEFAULT]

#
# From keystone
#

# A "shared secret" that can be used to bootstrap Keystone. This "token" does
# not represent a user, and carries no explicit authorization. If set to
# `None`, the value is ignored and the `admin_token` log in mechanism is
# effectively disabled. To completely disable `admin_token` in production
# (highly recommended), remove AdminTokenAuthMiddleware from your paste
# application pipelines (for example, in keystone-paste.ini). (string value)
#admin_token = <None>

# The base public endpoint URL for Keystone that is advertised to clients
# (NOTE: this does NOT affect how Keystone listens for connections). Defaults
# to the base host URL of the request. E.g. a request to
# http://server:5000/v3/users will default to http://server:5000. You should
# only need to set this value if the base URL contains a path (e.g. /prefix/v3)
# or the endpoint should be found on a different server. (string value)
#public_endpoint = <None>

# The base admin endpoint URL for Keystone that is advertised to clients (NOTE:
# this does NOT affect how Keystone listens for connections). Defaults to the
# base host URL of the request. E.g. a request to http://server:35357/v3/users
# will default to http://server:35357. You should only need to set this value
# if the base URL contains a path (e.g. /prefix/v3) or the endpoint should be
# found on a different server. (string value)
#admin_endpoint = <None>

# Maximum depth of the project hierarchy, excluding the project acting as a
# domain at the top of the hierarchy. WARNING: setting it to a large value may
# adversely impact  performance. (integer value)

oslo.config

Sphinx Sample Config Generator

  • integrates with doc build

  • shows sample configuration file

  • allows sample configuration to be added to doc package

  • override default values for sample file

# in doc/source/conf.py

config_generator_config_file = '../../config-generator/myapp.conf'
sample_config_basename = 'myapp'


# in doc/source/sample_conf.rst

.. literalinclude:: myapp.conf.sample

oslo.config

Sphinx Reference Generator

  • Rendered HTML

  • Same Input as Config Generator

  • Namespace and Multi-Page Support for Organization

  • Link to Option Definitions from Other Places

---------------
glance-api.conf
---------------

.. show-options::
   :config-file: etc/oslo-config-generator/glance-api.conf

stevedore

List Plugins

  • Simple or Detailed

  • Includes Help Text from Code

Future Work

  • Refinements to Sphinx Integration

  • Sample Generator and Reference Docs for Policy

  • Move from PoC to Production

References

http://docs.openstack.org/developer/oslo.config

http://docs.openstack.org/developer/stevedore