From eb1546fdfc157ebce0d52cbee54e2898d13de245 Mon Sep 17 00:00:00 2001
From: Lance Bragstad <lbragstad@gmail.com>
Date: Fri, 1 Jun 2018 19:50:53 +0000
Subject: [PATCH] Update sphinxext to include scope_types in docs

Since we've added ``scope_types`` as an attribute to policy rules, it
makes sense to include this information in documentation. End users
will need to know what type of scope is required to pass a specific
policy rule when services start incorporating system scope and scope
types.

Change-Id: I86d89e9f45740b39cef04773cec8846c1ab97c3a
Closes-Bug: 1773473
---
 oslo_policy/sphinxext.py                      |  5 ++++
 oslo_policy/tests/test_sphinxext.py           | 30 +++++++++++++++++++
 ...e-types-to-sphinxext-cacd845c4575e965.yaml |  6 ++++
 3 files changed, 41 insertions(+)
 create mode 100644 releasenotes/notes/add-scope-types-to-sphinxext-cacd845c4575e965.yaml

diff --git a/oslo_policy/sphinxext.py b/oslo_policy/sphinxext.py
index 00b90c8f..c5c88971 100644
--- a/oslo_policy/sphinxext.py
+++ b/oslo_policy/sphinxext.py
@@ -62,6 +62,11 @@ def _format_policy_rule(rule):
             yield _indent(_indent('- **{}** ``{}``'.format(
                 operation['method'], operation['path'])))
 
+    if hasattr(rule, 'scope_types') and rule.scope_types is not None:
+        yield _indent(':Scope Types:')
+        for scope_type in rule.scope_types:
+            yield _indent(_indent('- **{}**'.format(scope_type)))
+
     yield ''
 
     if rule.description:
diff --git a/oslo_policy/tests/test_sphinxext.py b/oslo_policy/tests/test_sphinxext.py
index 7834b35f..591b72ec 100644
--- a/oslo_policy/tests/test_sphinxext.py
+++ b/oslo_policy/tests/test_sphinxext.py
@@ -71,3 +71,33 @@ class FormatPolicyTest(base.BaseTestCase):
 
             My sample rule
         """).lstrip(), results)
+
+    def test_with_scope_types(self):
+        operations = [
+            {'method': 'GET', 'path': '/foo'},
+            {'method': 'POST', 'path': '/some'}
+        ]
+        scope_types = ['bar']
+        rule = policy.DocumentedRuleDefault(
+            'rule_a', '@', 'My sample rule', operations,
+            scope_types=scope_types
+        )
+
+        results = '\n'.join(list(sphinxext._format_policy_section(
+            'foo', [rule]
+        )))
+
+        self.assertEqual(textwrap.dedent("""
+        foo
+        ===
+
+        ``rule_a``
+            :Default: ``@``
+            :Operations:
+                - **GET** ``/foo``
+                - **POST** ``/some``
+            :Scope Types:
+                - **bar**
+
+            My sample rule
+        """).lstrip(), results)
diff --git a/releasenotes/notes/add-scope-types-to-sphinxext-cacd845c4575e965.yaml b/releasenotes/notes/add-scope-types-to-sphinxext-cacd845c4575e965.yaml
new file mode 100644
index 00000000..47ee19d8
--- /dev/null
+++ b/releasenotes/notes/add-scope-types-to-sphinxext-cacd845c4575e965.yaml
@@ -0,0 +1,6 @@
+---
+fixes:
+  - |
+    [`bug 1773473 <https://bugs.launchpad.net/oslo.policy/+bug/1773473>`_]
+    The ``sphinxext`` extension for rendering policy documentation now supports
+    ``scope_types`` attributes.