Commit 3cb5c38e by Yumeng Bao Committed by zhurong

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
parent c8ba137b
......@@ -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
......
......@@ -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
......
=========================================================
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
===================
Configuration Guide
===================
.. toctree::
:maxdepth: 1
config-options
sample_config
sample_policy
===========================
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
====================
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
......@@ -14,6 +14,14 @@ Overview
user/architecture
user/usage
Configuration
-------------------
.. toctree::
:maxdepth: 1
configuration/index
User Documentation
-------------------
......
......@@ -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
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or sign in to comment