From e32cad03336d849a9d3d1e892f57de402b7f6faa Mon Sep 17 00:00:00 2001 From: Akihiro Motoki Date: Wed, 19 Jul 2017 20:06:12 +0000 Subject: [PATCH] Add auto-generated config reference oslo.config provides sphinx extensions to generate config reference and sample config files. This commit enables the auto-generation of the networking config reference. Part of doc-migration work Change-Id: I954f87aebab9c70c8a81e7383e7546035ff4a92c --- .gitignore | 1 + doc/source/_static/.placeholder | 0 doc/source/conf.py | 25 ++++++++++++++- doc/source/configuration/fwaas_driver.rst | 6 ++++ doc/source/configuration/index.rst | 32 +++++++++++++++++++ doc/source/configuration/neutron_fwaas.rst | 6 ++++ .../configuration/samples/fwaas_driver.rst | 8 +++++ .../configuration/samples/neutron_fwaas.rst | 8 +++++ doc/source/index.rst | 1 + 9 files changed, 86 insertions(+), 1 deletion(-) create mode 100644 doc/source/_static/.placeholder create mode 100644 doc/source/configuration/fwaas_driver.rst create mode 100644 doc/source/configuration/index.rst create mode 100644 doc/source/configuration/neutron_fwaas.rst create mode 100644 doc/source/configuration/samples/fwaas_driver.rst create mode 100644 doc/source/configuration/samples/neutron_fwaas.rst diff --git a/.gitignore b/.gitignore index e0216e106..18303f69d 100644 --- a/.gitignore +++ b/.gitignore @@ -6,6 +6,7 @@ cover/ covhtml/ dist/ doc/build +doc/source/_static/config_samples/*.sample doc/source/contributor/api/ etc/*.sample *.DS_Store diff --git a/doc/source/_static/.placeholder b/doc/source/_static/.placeholder new file mode 100644 index 000000000..e69de29bb diff --git a/doc/source/conf.py b/doc/source/conf.py index 8be2fe97b..9ef4f0725 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -46,6 +46,8 @@ extensions = ['sphinx.ext.autodoc', 'sphinx.ext.ifconfig', 'sphinx.ext.graphviz', 'sphinx.ext.todo', + 'oslo_config.sphinxext', + 'oslo_config.sphinxconfiggen', 'openstackdocstheme',] todo_include_todos = True @@ -163,7 +165,7 @@ html_theme = 'openstackdocs' # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". -# html_static_path = ['_static'] +html_static_path = ['_static'] # If not '', a 'Last updated on:' timestamp is inserted at every page bottom, # using the given strftime format. @@ -242,3 +244,24 @@ html_last_updated_fmt = '%Y-%m-%d %H:%M' repository_name = 'openstack/neutron-fwaas' bug_project = 'neutron' bug_tag = 'doc' + +# -- Options for oslo_config.sphinxconfiggen --------------------------------- + +_config_generator_config_files = [ + 'fwaas_driver.ini', + 'neutron_fwaas.conf', +] + + +def _get_config_generator_config_definition(config_file): + config_file_path = '../../etc/oslo-config-generator/%s' % conf + # oslo_config.sphinxconfiggen appends '.conf.sample' to the filename, + # strip file extentension (.conf or .ini). + output_file_path = '_static/config_samples/%s' % conf.rsplit('.', 1)[0] + return (config_file_path, output_file_path) + + +config_generator_config_file = [ + _get_config_generator_config_definition(conf) + for conf in _config_generator_config_files +] diff --git a/doc/source/configuration/fwaas_driver.rst b/doc/source/configuration/fwaas_driver.rst new file mode 100644 index 000000000..015740d3f --- /dev/null +++ b/doc/source/configuration/fwaas_driver.rst @@ -0,0 +1,6 @@ +================ +fwaas_driver.ini +================ + +.. show-options:: + :config-file: etc/oslo-config-generator/fwaas_driver.ini diff --git a/doc/source/configuration/index.rst b/doc/source/configuration/index.rst new file mode 100644 index 000000000..7edd2a247 --- /dev/null +++ b/doc/source/configuration/index.rst @@ -0,0 +1,32 @@ +.. _configuring: + +============================= +Neutron Configuration Options +============================= + +This section provides a list of all possible options for each +configuration file. + +Configuration Reference +----------------------- + +Neutron uses the following configuration files for its various services. + +.. toctree:: + :glob: + :maxdepth: 1 + + * + +Sample Configuration Files +-------------------------- + +The following are sample configuration files for all Neutron services and +utilities. These are generated from code and reflect the current state of code +in the Neutron repository. + +.. toctree:: + :glob: + :maxdepth: 1 + + samples/* diff --git a/doc/source/configuration/neutron_fwaas.rst b/doc/source/configuration/neutron_fwaas.rst new file mode 100644 index 000000000..e390f0f1b --- /dev/null +++ b/doc/source/configuration/neutron_fwaas.rst @@ -0,0 +1,6 @@ +================== +neutron_fwaas.conf +================== + +.. show-options:: + :config-file: etc/oslo-config-generator/neutron_fwaas.conf diff --git a/doc/source/configuration/samples/fwaas_driver.rst b/doc/source/configuration/samples/fwaas_driver.rst new file mode 100644 index 000000000..2314f4ce4 --- /dev/null +++ b/doc/source/configuration/samples/fwaas_driver.rst @@ -0,0 +1,8 @@ +======================= +Sample fwaas_driver.ini +======================= + +This sample configuration can also be viewed in `the raw format +<../../_static/config_samples/fwaas_driver.conf.sample>`_. + +.. literalinclude:: ../../_static/config_samples/fwaas_driver.conf.sample diff --git a/doc/source/configuration/samples/neutron_fwaas.rst b/doc/source/configuration/samples/neutron_fwaas.rst new file mode 100644 index 000000000..1e1fd0ced --- /dev/null +++ b/doc/source/configuration/samples/neutron_fwaas.rst @@ -0,0 +1,8 @@ +========================= +Sample neutron_fwaas.conf +========================= + +This sample configuration can also be viewed in `the raw format +<../../_static/config_samples/neutron_fwaas.conf.sample>`_. + +.. literalinclude:: ../../_static/config_samples/neutron_fwaas.conf.sample diff --git a/doc/source/index.rst b/doc/source/index.rst index 19fa0755a..38fe0fcd8 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -9,6 +9,7 @@ General Information and Other Project References: :maxdepth: 2 install/index + configuration/index contributor/index .. rubric:: Indices and tables