====================================
Sphinx Oslo Sample Config Generation
====================================

Included with oslo.config is a sphinx extension to generate a sample config
file at the beginning of each sphinx build. To activate the extension add
``oslo_config.sphinxconfiggen`` to the list of extensions in your sphinx
``conf.py``.

Then you just need to use the ``config_generator_config_file`` option to point
the config generator at the config file which tells it how to generate the
sample config. If one isn't specified or it doesn't point to a real file the
sample config file generation will be skipped.

To generate multiple files, set ``config_generator_config_file`` to a
list of tuples containing the input filename and the base name for the
output file.

The output value can be ``None``, in which case the name is taken from
the input value.

The input name can be an full path or a value relative to the
documentation source directory.

For example::

  config_generator_config_file = [
      ('../../etc/glance-api.conf', 'api'),
      ('../../etc/glance-cache.conf', 'cache'),
      ('../../etc/glance-glare.conf', None),
      ('../../etc/glance-registry.conf', None),
      ('../../etc/glance-scrubber.conf', None),
  ]

Produces the output files ``api.conf.sample``, ``cache.conf.sample``,
``glance-glare.conf.sample``, ``glance-registry.conf.sample``, and
``glance-scrubber.conf.sample``.

Output File Name
----------------

By default the sphinx plugin will generate the sample config file and
name the file ``sample.config``. However, if for whatever reason you'd
like the name to be more specific to the project name you can use the
``sample_config_basename`` config option to specify the project
name. If it's set the output filename will be that value with a
``.conf.sample`` extension. For example if you set the value to
"``nova``" the output filename will be "``nova.conf.sample``". You can
also include a subdirectory off of the documentation source directory
as part of this value.