From 3cb5c38edb4f8d765ff426fa2ce682b8687db50f Mon Sep 17 00:00:00 2001 From: Yumeng Bao Date: Fri, 3 Aug 2018 16:53:12 +0800 Subject: [PATCH] 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 | 4 +++- doc/source/conf.py | 25 +++++++++++++++++++-- doc/source/configuration/config-options.rst | 9 ++++++++ doc/source/configuration/index.rst | 10 +++++++++ doc/source/configuration/sample_config.rst | 12 ++++++++++ doc/source/configuration/sample_policy.rst | 18 +++++++++++++++ doc/source/index.rst | 8 +++++++ test-requirements.txt | 1 - 8 files changed, 83 insertions(+), 4 deletions(-) create mode 100644 doc/source/configuration/config-options.rst create mode 100644 doc/source/configuration/index.rst create mode 100644 doc/source/configuration/sample_config.rst create mode 100644 doc/source/configuration/sample_policy.rst diff --git a/.gitignore b/.gitignore index 5870aa5c..f57cebe3 100644 --- a/.gitignore +++ b/.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 diff --git a/doc/source/conf.py b/doc/source/conf.py index e3892e46..68f41252 100755 --- a/doc/source/conf.py +++ b/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 diff --git a/doc/source/configuration/config-options.rst b/doc/source/configuration/config-options.rst new file mode 100644 index 00000000..c977a1b2 --- /dev/null +++ b/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 ` is also available. + +.. show-options:: + :config-file: tools/config/cyborg-config-generator.conf diff --git a/doc/source/configuration/index.rst b/doc/source/configuration/index.rst new file mode 100644 index 00000000..a8cde7ca --- /dev/null +++ b/doc/source/configuration/index.rst @@ -0,0 +1,10 @@ +=================== +Configuration Guide +=================== + +.. toctree:: + :maxdepth: 1 + + config-options + sample_config + sample_policy diff --git a/doc/source/configuration/sample_config.rst b/doc/source/configuration/sample_config.rst new file mode 100644 index 00000000..de747357 --- /dev/null +++ b/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 diff --git a/doc/source/configuration/sample_policy.rst b/doc/source/configuration/sample_policy.rst new file mode 100644 index 00000000..ce3823e7 --- /dev/null +++ b/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 `_. + +.. literalinclude:: /_static/cyborg.policy.yaml.sample diff --git a/doc/source/index.rst b/doc/source/index.rst index d7355d2d..a9415fc7 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -14,6 +14,14 @@ Overview user/architecture user/usage +Configuration +------------------- + +.. toctree:: + :maxdepth: 1 + + configuration/index + User Documentation ------------------- diff --git a/test-requirements.txt b/test-requirements.txt index fb14fb35..5521794e 100644 --- a/test-requirements.txt +++ b/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