sphinxext: Use field lists in output

The 'sphinxext' module provided by 'oslo.config' uses field lists [1] for
its defaults. Provide some cross-promotional, deal mechanics, revenue
streams, jargon synergy between these two plugins (i.e. make them look
similar).

This message was approved by Jack Donaghy [2].

[1] http://docutils.sourceforge.net/docs/user/rst/quickref.html#field-lists
[2] https://youtu.be/aocZo3oeNxw

Change-Id: I6e478152a278a877ae37588be930b0b833eb09cd

oslo_policy/sphinxext.py

@@ -43,37 +43,31 @@ def _format_policy_rule(rule):
     For example:
 
         ``os_compute_api:servers:create``
+            :Default: ``rule:admin_or_owner``
+            :Operations:
+              - **POST** ``/servers``
+
             Create a server
-
-            Default::
-
-                rule:admin_or_owner
-
-            Operations:
-
-            - **POST** ``/servers``
     """
     yield '``{}``'.format(rule.name)
 
+    yield _indent(':Default: ``{}``'.format(rule.check_str))
+
+    if hasattr(rule, 'operations'):
+        yield _indent(':Operations:')
+        for operation in rule.operations:
+            yield _indent(_indent('- **{}** ``{}``'.format(
+                operation['method'], operation['path'])))
+
+    yield ''
+
     if rule.description:
         for line in statemachine.string2lines(
                 rule.description, tab_width=4, convert_whitespace=True):
             if line:
                 yield _indent(line)
-
-        yield ''
-
-    yield _indent('Default::')
-    yield ''
-    yield _indent(_indent(rule.check_str))
-
-    if hasattr(rule, 'operations'):
-        yield ''
-        yield _indent('Operations:')
-        yield ''
-        for operation in rule.operations:
-            yield _indent('- **{}** ``{}``'.format(operation['method'],
-                                                   operation['path']))
+    else:
+        yield _indent('(no description provided)')
 
     yield ''
 

oslo_policy/tests/test_sphinxext.py

@@ -31,9 +31,9 @@ class FormatPolicyTest(base.BaseTestCase):
         ===
 
         ``rule_a``
-            Default::
+            :Default: ``@``
 
-                @
+            (no description provided)
         """).lstrip(), results)
 
     def test_with_description(self):
@@ -46,11 +46,9 @@ class FormatPolicyTest(base.BaseTestCase):
         ===
 
         ``rule_a``
+            :Default: ``@``
+
             My sample rule
-
-            Default::
-
-                @
         """).lstrip(), results)
 
     def test_with_operations(self):
@@ -66,14 +64,10 @@ class FormatPolicyTest(base.BaseTestCase):
         ===
 
         ``rule_a``
+            :Default: ``@``
+            :Operations:
+                - **GET** ``/foo``
+                - **POST** ``/some``
+
             My sample rule
-
-            Default::
-
-                @
-
-            Operations:
-
-            - **GET** ``/foo``
-            - **POST** ``/some``
         """).lstrip(), results)