From c314db081ebefe347f76de775dfd9021cf6f024e Mon Sep 17 00:00:00 2001 From: Akihiro Motoki Date: Sat, 22 Jul 2017 18:02:42 +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. Note that this commit just adds the configuration references for existing genconfig entries. I haven't checked there are options uncovered. If any, this will be a potential future work. Part of doc-migration work Change-Id: I4e150b6045e5e9c56cbe7262b31ee0d82dcb6c69 --- .gitignore | 1 + doc/source/_static/.placeholder | 0 doc/source/conf.py | 25 +++++++++++++-- doc/source/configuration/bgp_dragent.rst | 6 ++++ doc/source/configuration/index.rst | 31 +++++++++++++++++++ .../configuration/samples/bgp_dragent.rst | 8 +++++ doc/source/index.rst | 1 + 7 files changed, 70 insertions(+), 2 deletions(-) create mode 100644 doc/source/_static/.placeholder create mode 100644 doc/source/configuration/bgp_dragent.rst create mode 100644 doc/source/configuration/index.rst create mode 100644 doc/source/configuration/samples/bgp_dragent.rst diff --git a/.gitignore b/.gitignore index 2eb709a7..475071ad 100644 --- a/.gitignore +++ b/.gitignore @@ -6,6 +6,7 @@ cover/ covhtml/ dist/ doc/build +doc/source/_static/config_samples/*.sample etc/*.sample *.DS_Store *.pyc diff --git a/doc/source/_static/.placeholder b/doc/source/_static/.placeholder new file mode 100644 index 00000000..e69de29b diff --git a/doc/source/conf.py b/doc/source/conf.py index 24392c94..c825df50 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -22,7 +22,9 @@ sys.path.insert(0, os.path.abspath('../..')) extensions = [ 'sphinx.ext.autodoc', #'sphinx.ext.intersphinx', - 'openstackdocstheme' + 'openstackdocstheme', + 'oslo_config.sphinxext', + 'oslo_config.sphinxconfiggen', ] # openstackdocstheme options @@ -61,7 +63,7 @@ pygments_style = 'sphinx' # html_theme_path = ["."] # html_theme = '_theme' html_theme = 'openstackdocs' -# html_static_path = ['static'] +html_static_path = ['_static'] html_last_updated_fmt = '%Y-%m-%d %H:%M' @@ -80,3 +82,22 @@ latex_documents = [ # Example configuration for intersphinx: refer to the Python standard library. #intersphinx_mapping = {'http://docs.python.org/': None} + +# -- Options for oslo_config.sphinxconfiggen --------------------------------- + +_config_generator_config_files = [ + 'bgp_dragent.ini', +] + +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/bgp_dragent.rst b/doc/source/configuration/bgp_dragent.rst new file mode 100644 index 00000000..9bcb5119 --- /dev/null +++ b/doc/source/configuration/bgp_dragent.rst @@ -0,0 +1,6 @@ +=============== +bgp_dragent.ini +=============== + +.. show-options:: + :config-file: etc/oslo-config-generator/bgp_dragent.ini diff --git a/doc/source/configuration/index.rst b/doc/source/configuration/index.rst new file mode 100644 index 00000000..b5616f4f --- /dev/null +++ b/doc/source/configuration/index.rst @@ -0,0 +1,31 @@ +===================== +Configuration Options +===================== + +This section provides a list of all possible options for each +configuration file. + +Configuration Reference +----------------------- + +neutron-dynamic-routing uses the following configuration files for its +various services. + +.. toctree:: + :glob: + :maxdepth: 1 + + * + +Sample Configuration Files +-------------------------- + +The following are sample configuration files for neutron-dynamic-routing. +These are generated from code and reflect the current state of code +in the neutron-dynamic-routing repository. + +.. toctree:: + :glob: + :maxdepth: 1 + + samples/* diff --git a/doc/source/configuration/samples/bgp_dragent.rst b/doc/source/configuration/samples/bgp_dragent.rst new file mode 100644 index 00000000..2c5a26de --- /dev/null +++ b/doc/source/configuration/samples/bgp_dragent.rst @@ -0,0 +1,8 @@ +====================== +Sample bgp_dragent.ini +====================== + +This sample configuration can also be viewed in `the raw format +<../../_static/config_samples/bgp_dragent.conf.sample>`_. + +.. literalinclude:: ../../_static/config_samples/bgp_dragent.conf.sample diff --git a/doc/source/index.rst b/doc/source/index.rst index 4f1e6add..bc93a2ea 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -36,6 +36,7 @@ Contents install/index admin/index + configuration/index reference/index cli/index contributor/index