sample-generator: Improve YAML output

This commit makes the following minor improvements
in YAML output of oslopolicy-sample-generator.

* Add a blank line between policies.
  Previously when a deprecated rule exists there was no blank line
  between the deprecated rule and the next rule.
  It was not easy to identify the beginning of the next rule.
* Drop unnecessary blank line comment.
  If a policy is defined by RuleDefault instead of DocumentedRuleDefault
  there is no description and unnecessary blank line comment was added
  in an output YAML file.
* Honor newlines in deprecated_text.
  Previously newlines in deprecated_text were dropped by
  _format_help_text(). Main deprecation message and reason are
  processed separately and newlines are not dropped now.

Change-Id: I75889a1b05344a47135419d0553525f54c1a51b8

2 files changed, 25 insertions, 29 deletions

diff --git a/oslo_policy/generator.py b/oslo_policy/generator.py
index a35acae..244de03 100644
--- a/oslo_policy/generator.py
+++ b/oslo_policy/generator.py
@@ -186,12 +186,13 @@ def _format_rule_default_yaml(default, include_help=True, comment_rule=True,
                 '# Intended scope(s): ' + ', '.join(default.scope_types) + '\n'
             )
         comment = '#' if comment_rule else ''
-        text = ('%(help)s\n%(op)s%(scope)s%(comment)s%(text)s\n' %
-                {'help': _format_help_text(default.description),
-                 'op': op,
+        text = ('%(op)s%(scope)s%(comment)s%(text)s\n' %
+                {'op': op,
                  'scope': intended_scope,
                  'comment': comment,
                  'text': text})
+        if default.description:
+            text = _format_help_text(default.description) + '\n' + text
 
     if add_deprecated_rules and default.deprecated_for_removal:
         text = (
@@ -206,29 +207,24 @@ def _format_rule_default_yaml(default, include_help=True, comment_rule=True,
         # This issues a deprecation warning but aliases the old policy name
         # with the new policy name for compatibility.
         deprecated_text = (
-            'DEPRECATED\n"%(old_name)s":"%(old_check_str)s" has been '
-            'deprecated since %(since)s in favor of '
-            '"%(name)s":"%(check_str)s".\n%(reason)s'
+            '"%(old_name)s":"%(old_check_str)s" has been deprecated '
+            'since %(since)s in favor of "%(name)s":"%(check_str)s".'
         ) % {'old_name': default.deprecated_rule.name,
              'old_check_str': default.deprecated_rule.check_str,
              'since': default.deprecated_since,
              'name': default.name,
              'check_str': default.check_str,
-             'reason': default.deprecated_reason}
+             }
+        text = ('%(text)s# DEPRECATED\n%(deprecated_text)s\n%(reason)s\n' %
+                {'text': text,
+                 'reason': _format_help_text(default.deprecated_reason),
+                 'deprecated_text': _format_help_text(deprecated_text)})
 
         if default.name != default.deprecated_rule.name:
-            text = (
-                '%(text)s%(deprecated_text)s\n"%(old_name)s": "rule:%(name)s"'
-                '\n'
-            ) % {'text': text,
-                 'deprecated_text': _format_help_text(deprecated_text),
-                 'old_name': default.deprecated_rule.name,
-                 'name': default.name}
-        else:
-            text = (
-                '%(text)s%(deprecated_text)s\n'
-            ) % {'text': text,
-                 'deprecated_text': _format_help_text(deprecated_text)}
+            text += ('"%(old_name)s": "rule:%(name)s"\n' %
+                     {'old_name': default.deprecated_rule.name,
+                      'name': default.name})
+        text += '\n'
 
     return text
 
diff --git a/oslo_policy/tests/test_generator.py b/oslo_policy/tests/test_generator.py
index 91ad901..2835536 100644
--- a/oslo_policy/tests/test_generator.py
+++ b/oslo_policy/tests/test_generator.py
@@ -98,10 +98,8 @@ class GenerateSampleYAMLTestCase(base.PolicyBaseTestCase):
 # POST  /test/
 #"owner": "project_id:%(project_id)s"
 
-#
 #"shared": "field:networks:shared=True"
 
-#
 #"admin_or_owner": "rule:admin or rule:owner"
 
 '''
@@ -137,10 +135,8 @@ class GenerateSampleYAMLTestCase(base.PolicyBaseTestCase):
 # POST  /test/
 #"owner": "project_id:%(project_id)s"
 
-#
 #"shared": "field:networks:shared=True"
 
-#
 #"admin_or_owner": "rule:admin or rule:owner"
 
 '''
@@ -223,10 +219,12 @@ class GenerateSampleYAMLTestCase(base.PolicyBaseTestCase):
         expected = '''# Create a bar.
 #"foo:create_bar": "role:fizz"
 
-# DEPRECATED "foo:post_bar":"role:fizz" has been deprecated since N in
-# favor of "foo:create_bar":"role:fizz". foo:post_bar is being removed
-# in favor of foo:create_bar
+# DEPRECATED
+# "foo:post_bar":"role:fizz" has been deprecated since N in favor of
+# "foo:create_bar":"role:fizz".
+# foo:post_bar is being removed in favor of foo:create_bar
 "foo:post_bar": "rule:foo:create_bar"
+
 '''
         stdout = self._capture_stdout()
         with mock.patch('stevedore.named.NamedExtensionManager',
@@ -267,9 +265,11 @@ class GenerateSampleYAMLTestCase(base.PolicyBaseTestCase):
         expected = '''# Create a bar.
 #"foo:create_bar": "role:fizz"
 
-# DEPRECATED "foo:create_bar":"role:old" has been deprecated since N
-# in favor of "foo:create_bar":"role:fizz". role:fizz is a more sane
-# default for foo:create_bar
+# DEPRECATED
+# "foo:create_bar":"role:old" has been deprecated since N in favor of
+# "foo:create_bar":"role:fizz".
+# role:fizz is a more sane default for foo:create_bar
+
 '''
         stdout = self._capture_stdout()
         with mock.patch('stevedore.named.NamedExtensionManager',