From fb1e9879e6df063b0a01ed0a56637d432ded9f1f Mon Sep 17 00:00:00 2001 From: Stephen Finucane Date: Mon, 26 Sep 2016 15:01:28 +0100 Subject: [PATCH] Add sphinx extension to build sample policy Provide a way to include a sample policy file in a project's documentation. This harnesses the same generator utilities used in standard policy file generation. Change-Id: I4b04044c18ea9f2b1d55785686982af9032a8495 --- doc/source/index.rst | 1 + doc/source/sphinxpolicygen.rst | 48 ++++++++++++ oslo_policy/sphinxpolicygen.py | 73 +++++++++++++++++++ oslo_policy/tests/test_sphinxpolicygen.py | 52 +++++++++++++ .../add-sphinxpolicygen-39e2f8fa24930b0c.yaml | 5 ++ 5 files changed, 179 insertions(+) create mode 100644 doc/source/sphinxpolicygen.rst create mode 100644 oslo_policy/sphinxpolicygen.py create mode 100644 oslo_policy/tests/test_sphinxpolicygen.py create mode 100644 releasenotes/notes/add-sphinxpolicygen-39e2f8fa24930b0c.yaml diff --git a/doc/source/index.rst b/doc/source/index.rst index 8357baca..a4338142 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -14,6 +14,7 @@ Contents opts cli contributing + sphinxpolicygen history Indices and tables diff --git a/doc/source/sphinxpolicygen.rst b/doc/source/sphinxpolicygen.rst new file mode 100644 index 00000000..bf9fc89c --- /dev/null +++ b/doc/source/sphinxpolicygen.rst @@ -0,0 +1,48 @@ +==================================== +Sphinx Oslo Sample Policy Generation +==================================== + +.. note:: + This extension relies on ``oslopolicy-sample-generator``, which requires + configuration of policies in code to function. Refer to the :doc:`usage` + guide for more information. + +oslo.policy includes a sphinx extension to generate a sample policy file at the +beginning of each sphinx build. This sample policy file can then be included in +your documents as a raw file, for example, via the ``literalinclude`` directive. + +To activate the extension add ``oslo_policy.sphinxpolicygen`` to the list of +extensions in your sphinx ``conf.py``. Once enabled, you need to define two +options: ``policy_generator_config_file`` and ``sample_policy_basename``. For +example:: + + policy_generator_config_file = '../../etc/nova/nova-policy-generator.conf' + sample_policy_basename = '_static/nova' + +where: + +``policy_generator_config_file`` + Path to an configuration file used with the ``oslopolicy-sample-generator`` + utility. This can be an full path or a value relative to the documentation + source directory (``app.srcdir``). If this option is not specified or is + invalid then the sample policy file generation will be skipped. + +``sample_policy_basename`` + Base name of the output file. This name will be appended with a + ``.policy.yaml.sample`` extension to generate the final output file and the + path is relative to documentation source directory (``app.srcdir``). As such, + using the above example, the policy file will be output to + ``_static/nova.policy.yaml.sample``. If this option is not specified, the + file will be output to ``sample.policy.yaml``. + +Once configured, you can include this configuration file in your source: + +.. code:: reST + + ============= + Sample Policy + ============= + + Here is a sample policy file. + + .. literalinclude:: _static/nova.policy.yaml.sample diff --git a/oslo_policy/sphinxpolicygen.py b/oslo_policy/sphinxpolicygen.py new file mode 100644 index 00000000..113e0406 --- /dev/null +++ b/oslo_policy/sphinxpolicygen.py @@ -0,0 +1,73 @@ +# Copyright 2015 Hewlett-Packard Development Company, L.P. +# Copyright 2016 Red Hat, Inc. +# +# Licensed under the Apache License, Version 2.0 (the "License"); you may +# not use this file except in compliance with the License. You may obtain +# a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT +# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the +# License for the specific language governing permissions and limitations +# under the License. + +"""Generate a sample policy file.""" + +import os + +from oslo_policy import generator + + +def generate_sample(app): + """Generate a sample policy file.""" + + if not app.config.policy_generator_config_file: + app.warn("No policy_generator_config_file is specified, " + "skipping sample policy generation") + return + + _generate_sample(app, + app.config.policy_generator_config_file, + app.config.sample_policy_basename) + + +def _generate_sample(app, policy_file, base_name): + + def info(msg): + app.info('[%s] %s' % (__name__, msg)) + + # If we are given a file that isn't an absolute path, look for it + # in the source directory if it doesn't exist. + candidates = [ + policy_file, + os.path.join(app.srcdir, policy_file,), + ] + for c in candidates: + if os.path.isfile(c): + info('reading config generator instructions from %s' % c) + config_path = c + break + else: + raise ValueError( + "Could not find policy_generator_config_file %r" % + app.config.policy_generator_config_file) + + if base_name: + out_file = os.path.join(app.srcdir, base_name) + '.policy.yaml.sample' + if not os.path.isdir(os.path.dirname(os.path.abspath(out_file))): + os.mkdir(os.path.dirname(os.path.abspath(out_file))) + else: + file_name = 'sample.policy.yaml' + out_file = os.path.join(app.srcdir, file_name) + + info('writing sample policy to %s' % out_file) + generator.generate_sample(args=['--config-file', config_path, + '--output-file', out_file]) + + +def setup(app): + app.add_config_value('policy_generator_config_file', None, 'env') + app.add_config_value('sample_policy_basename', None, 'env') + app.connect('builder-inited', generate_sample) diff --git a/oslo_policy/tests/test_sphinxpolicygen.py b/oslo_policy/tests/test_sphinxpolicygen.py new file mode 100644 index 00000000..fa9a3a14 --- /dev/null +++ b/oslo_policy/tests/test_sphinxpolicygen.py @@ -0,0 +1,52 @@ +# Licensed under the Apache License, Version 2.0 (the "License"); you may +# not use this file except in compliance with the License. You may obtain +# a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT +# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the +# License for the specific language governing permissions and limitations +# under the License. + +import mock +from oslotest import base + +from oslo_policy import sphinxpolicygen + + +class SingleSampleGenerationTest(base.BaseTestCase): + + @mock.patch('os.path.isdir') + @mock.patch('os.path.isfile') + @mock.patch('oslo_policy.generator.generate_sample') + def test_sample_gen_with_single_config_file(self, sample, isfile, isdir): + isfile.side_effect = [False, True] + isdir.return_value = True + + config = mock.Mock(policy_generator_config_file='nova.conf', + sample_policy_basename='nova') + app = mock.Mock(srcdir='/opt/nova', config=config) + sphinxpolicygen.generate_sample(app) + + sample.assert_called_once_with(args=[ + '--config-file', '/opt/nova/nova.conf', + '--output-file', '/opt/nova/nova.policy.yaml.sample']) + + @mock.patch('os.path.isdir') + @mock.patch('os.path.isfile') + @mock.patch('oslo_policy.generator.generate_sample') + def test_sample_gen_with_single_config_file_no_base(self, sample, isfile, + isdir): + isfile.side_effect = [False, True] + isdir.return_value = True + + config = mock.Mock(policy_generator_config_file='nova.conf', + sample_policy_basename=None) + app = mock.Mock(srcdir='/opt/nova', config=config) + sphinxpolicygen.generate_sample(app) + + sample.assert_called_once_with(args=[ + '--config-file', '/opt/nova/nova.conf', + '--output-file', '/opt/nova/sample.policy.yaml']) diff --git a/releasenotes/notes/add-sphinxpolicygen-39e2f8fa24930b0c.yaml b/releasenotes/notes/add-sphinxpolicygen-39e2f8fa24930b0c.yaml new file mode 100644 index 00000000..ac95c623 --- /dev/null +++ b/releasenotes/notes/add-sphinxpolicygen-39e2f8fa24930b0c.yaml @@ -0,0 +1,5 @@ +--- +features: + - | + Add ``sphinxpolicygen`` Sphinx plugin, which can be used to generate a + sample policy file for use in documentation.