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
This commit is contained in:
Akihiro Motoki 2017-07-22 18:02:42 +00:00
parent d8c2c9e562
commit c314db081e
7 changed files with 70 additions and 2 deletions

1
.gitignore vendored
View File

@ -6,6 +6,7 @@ cover/
covhtml/ covhtml/
dist/ dist/
doc/build doc/build
doc/source/_static/config_samples/*.sample
etc/*.sample etc/*.sample
*.DS_Store *.DS_Store
*.pyc *.pyc

View File

View File

@ -22,7 +22,9 @@ sys.path.insert(0, os.path.abspath('../..'))
extensions = [ extensions = [
'sphinx.ext.autodoc', 'sphinx.ext.autodoc',
#'sphinx.ext.intersphinx', #'sphinx.ext.intersphinx',
'openstackdocstheme' 'openstackdocstheme',
'oslo_config.sphinxext',
'oslo_config.sphinxconfiggen',
] ]
# openstackdocstheme options # openstackdocstheme options
@ -61,7 +63,7 @@ pygments_style = 'sphinx'
# html_theme_path = ["."] # html_theme_path = ["."]
# html_theme = '_theme' # html_theme = '_theme'
html_theme = 'openstackdocs' html_theme = 'openstackdocs'
# html_static_path = ['static'] html_static_path = ['_static']
html_last_updated_fmt = '%Y-%m-%d %H:%M' 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. # Example configuration for intersphinx: refer to the Python standard library.
#intersphinx_mapping = {'http://docs.python.org/': None} #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
]

View File

@ -0,0 +1,6 @@
===============
bgp_dragent.ini
===============
.. show-options::
:config-file: etc/oslo-config-generator/bgp_dragent.ini

View File

@ -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/*

View File

@ -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

View File

@ -36,6 +36,7 @@ Contents
install/index install/index
admin/index admin/index
configuration/index
reference/index reference/index
cli/index cli/index
contributor/index contributor/index