From ca709827758164b4f31ad1eddbd86cb50f0bfe37 Mon Sep 17 00:00:00 2001 From: Lance Bragstad Date: Thu, 20 Apr 2017 22:37:22 +0000 Subject: [PATCH] Include sample policy file in documentation Since we're moving all policy into code and documenting it there we should generate those docs automatically, so they are less likely to be out-of-date. Change-Id: If00cd3bcc654a45944c0bc8b3f146c75bd970f9a partially-implements: blueprint policy-docs --- .gitignore | 2 ++ doc/source/conf.py | 4 ++++ doc/source/index.rst | 5 +++-- doc/source/sample_policy.rst | 15 +++++++++++++++ 4 files changed, 24 insertions(+), 2 deletions(-) create mode 100644 doc/source/sample_policy.rst diff --git a/.gitignore b/.gitignore index 735cf7ef74..aab1d819dd 100644 --- a/.gitignore +++ b/.gitignore @@ -36,3 +36,5 @@ keystone/locale/*/LC_MESSAGES/*.mo releasenotes/build # sample config included in docs doc/source/_static/keystone.conf.sample +# sample policy file included in docs +doc/source/_static/keystone.policy.yaml.sample diff --git a/doc/source/conf.py b/doc/source/conf.py index 6cf48b5729..4dc3c47dc0 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -51,6 +51,7 @@ extensions = ['sphinx.ext.autodoc', 'sphinx.ext.coverage', 'sphinx.ext.viewcode', 'oslo_config.sphinxconfiggen', + 'oslo_policy.sphinxpolicygen', 'oslosphinx', 'ext.support_matrix', ] @@ -58,6 +59,9 @@ extensions = ['sphinx.ext.autodoc', config_generator_config_file = '../../config-generator/keystone.conf' sample_config_basename = '_static/keystone' +policy_generator_config_file = '../../etc/keystone-policy-generator.conf' +sample_policy_basename = '_static/keystone' + todo_include_todos = True # Add any paths that contain templates here, relative to this directory. diff --git a/doc/source/index.rst b/doc/source/index.rst index b07f9f16f4..54e20a2986 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -102,13 +102,14 @@ Developers Documentation devref/http-api devref/services -Sample Configuration File -========================= +Sample Files +============ .. toctree:: :maxdepth: 1 sample_config + sample_policy Man Pages ========= diff --git a/doc/source/sample_policy.rst b/doc/source/sample_policy.rst new file mode 100644 index 0000000000..0b54621674 --- /dev/null +++ b/doc/source/sample_policy.rst @@ -0,0 +1,15 @@ +====================== +Keystone Sample Policy +====================== + +The following is a sample keystone 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 keystone 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. + +The sample policy file can also be viewed in `file form <_static/keystone.policy.yaml.sample>`_. + +.. literalinclude:: _static/keystone.policy.yaml.sample