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

@@ -14,6 +14,7 @@ Contents
    opts
    cli
    contributing
+   sphinxpolicygen
    history
 
 Indices and tables

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

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)

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'])

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.