Docs: Autogenerate config documentation

Ensure the documentation is kept up to date by automatically
generating it from the source when the docs are built.

This patch:
1.replace oslosphinx with openstackdocstheme since oslosphinx is obsolete
2.add oslo_config.sphinxconfiggen to generate sample conf file
3.add oslo_policy.sphinxpolicygen to generate sample policy file

Change-Id: I39f03023f0a85e4c8943925268ab3e9066975630

.gitignore

@@ -12,7 +12,9 @@ dist
 build/*
 *.DS_Store
 ChangeLog
-
+#Autogenerated Documentation
+doc/source/_static/cyborg.conf.sample
+doc/source/_static/cyborg.policy.yaml.sample
 # Sample profile
 etc/cyborg/policy.json.sample
 etc/cyborg/cyborg.conf.sample

doc/source/conf.py

@@ -23,7 +23,11 @@ sys.path.insert(0, os.path.abspath('../..'))
 extensions = [
     'sphinx.ext.autodoc',
     #'sphinx.ext.intersphinx',
-    'oslosphinx'
+    'openstackdocstheme',
+    'oslo_config.sphinxconfiggen',
+    'oslo_config.sphinxext',
+    'oslo_policy.sphinxext',
+    'oslo_policy.sphinxpolicygen',
 ]
 
 # autodoc generation is a bit aggressive and a nuisance when doing heavy
@@ -40,6 +44,20 @@ master_doc = 'index'
 project = u'cyborg'
 copyright = u'2013, OpenStack Foundation'
 
+# openstackdocstheme options
+repository_name = 'openstack/cyborg'
+bug_project = 'cyborg'
+bug_tag = ''
+html_last_updated_fmt = '%Y-%m-%d %H:%M'
+
+config_generator_config_file = '../../tools/config/cyborg-config-generator.conf'
+sample_config_basename = '_static/cyborg'
+
+policy_generator_config_file = [
+    ('../../tools/config/cyborg-policy-generator.conf',
+     '_static/cyborg'),
+]
+
 # If true, '()' will be appended to :func: etc. cross-reference text.
 add_function_parentheses = True
 
@@ -56,7 +74,10 @@ pygments_style = 'sphinx'
 # Sphinx are currently 'default' and 'sphinxdoc'.
 # html_theme_path = ["."]
 # html_theme = '_theme'
-# html_static_path = ['static']
+# 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']
 
 # Output file base name for HTML help builder.
 htmlhelp_basename = '%sdoc' % project

doc/source/configuration/config-options.rst

@@ -0,0 +1,9 @@
+=========================================================
+Configuration options for the Acceleration service
+=========================================================
+
+The following options can be set in the ``/etc/cyborg/cyborg.conf`` config file
+A :doc:`sample configuration file <sample_config>` is also available.
+
+.. show-options::
+   :config-file: tools/config/cyborg-config-generator.conf

doc/source/configuration/index.rst

@@ -0,0 +1,10 @@
+===================
+Configuration Guide
+===================
+
+.. toctree::
+   :maxdepth: 1
+
+   config-options
+   sample_config
+   sample_policy

doc/source/configuration/sample_config.rst

@@ -0,0 +1,12 @@
+===========================
+Cyborg Configuration Sample
+===========================
+
+The following is a sample cyborg configuration for adaptation and use. It is
+auto-generated from cyborg when this documentation is built, so if you are
+having issues with an option, please compare your version of cyborg with the
+version of this documentation.
+
+The sample configuration can also be downloaded in `file form <../_static/cyborg.conf.sample>`_.
+
+.. literalinclude:: ../_static/cyborg.conf.sample

doc/source/configuration/sample_policy.rst

@@ -0,0 +1,18 @@
+====================
+Cyborg Sample Policy
+====================
+
+The following is a sample cyborg policy file that has been auto-generated
+from default policy values in code. If you're using the default policies, then
+the maintenance of this file is not necessary, and it should not be copied into
+a deployment. Doing so will result in duplicate policy definitions. It is here
+to help explain which policy operations protect specific cyborg APIs, but it
+is not suggested to copy and paste into a deployment unless you're planning on
+providing a different policy for an operation that is not the default.
+
+If you wish build a policy file, you can also use ``tox -e genpolicy`` to
+generate it.
+
+The sample policy file can also be downloaded in `file form </_static/cyborg.policy.yaml.sample>`_.
+
+.. literalinclude:: /_static/cyborg.policy.yaml.sample

doc/source/index.rst

@@ -14,6 +14,14 @@ Overview
     user/architecture
     user/usage
 
+Configuration
+-------------------
+
+.. toctree::
+    :maxdepth: 1
+
+    configuration/index
+
 User Documentation
 -------------------
 

test-requirements.txt

@@ -9,7 +9,6 @@ fixtures>=3.0.0 # Apache-2.0/BSD
 mock>=2.0.0 # BSD
 sphinx>=1.6.2,!=1.6.6,!=1.6.7 # BSD
 ddt>=1.0.1 # MIT
-oslosphinx>=4.7.0 # Apache-2.0
 oslotest>=3.2.0 # Apache-2.0
 stestr>=2.0.0 # Apache-2.0/BSD
 testresources>=2.0.0 # Apache-2.0/BSD