6f2c57ca10
We landed the feature to let the sphinx integration work with multiple input and output files, but we didn't update the docs for it. Change-Id: I1ef3f91aed3bdbcfdff4f8afc5fa325b34008495 Signed-off-by: Doug Hellmann <doug@doughellmann.com>
2.0 KiB
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.