# 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.

this page last updated: 2026-07-14 13:15:13

Except where otherwise noted, this document is licensed under Creative Commons Attribution 3.0 License. See all OpenStack Legal Documents.

found an error? report a bug