From 7ade2ed547e690d4737114af467088df17a63ac8 Mon Sep 17 00:00:00 2001
From: Davanum Srinivas <davanum@gmail.com>
Date: Mon, 9 Oct 2017 12:05:10 -0400
Subject: [PATCH] Documentation and release notes for plugins

In Icde2b26a38d7c7842defae053228d9208454b969, we added support for
stevedore based external/custom plugins. In this changeset, we
add a release note and documentation on how things work.

Change-Id: Ie0b773dc1147f5ef898d17e8f84c946c39fdf5cd
---
 doc/source/conf.py                            |  7 +++
 doc/source/user/index.rst                     |  1 +
 doc/source/user/plugins.rst                   | 51 +++++++++++++++++++
 ...ustom_rule_check_plugins-3c15c2c7ca5e.yaml |  6 +++
 4 files changed, 65 insertions(+)
 create mode 100644 doc/source/user/plugins.rst
 create mode 100644 releasenotes/notes/add_custom_rule_check_plugins-3c15c2c7ca5e.yaml

diff --git a/doc/source/conf.py b/doc/source/conf.py
index 5797d628..16f161e9 100755
--- a/doc/source/conf.py
+++ b/doc/source/conf.py
@@ -22,6 +22,7 @@ sys.path.insert(0, os.path.abspath('../..'))
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
 extensions = [
     'sphinx.ext.autodoc',
+    'sphinx.ext.extlinks',
     #'sphinx.ext.intersphinx',
     'openstackdocstheme',
     'oslo_config.sphinxext',
@@ -50,6 +51,7 @@ exclude_patterns = ['api/oslo_policy.tests.*', 'api/setup.rst']
 # General information about the project.
 project = u'oslo.policy'
 copyright = u'2014, OpenStack Foundation'
+source_tree = 'https://git.openstack.org/cgit/openstack/oslo.policy/tree'
 
 # If true, '()' will be appended to :func: etc. cross-reference text.
 add_function_parentheses = True
@@ -86,5 +88,10 @@ latex_documents = [
      u'OpenStack Foundation', 'manual'),
 ]
 
+# Shortened external links.
+extlinks = {
+    'example': (source_tree + '/oslo_policy/%s', ''),
+}
+
 # Example configuration for intersphinx: refer to the Python standard library.
 #intersphinx_mapping = {'http://docs.python.org/': None}
diff --git a/doc/source/user/index.rst b/doc/source/user/index.rst
index cfb053b4..47af2bb8 100644
--- a/doc/source/user/index.rst
+++ b/doc/source/user/index.rst
@@ -5,6 +5,7 @@
 .. toctree::
 
    usage
+   plugins
    sphinxpolicygen
    history
 
diff --git a/doc/source/user/plugins.rst b/doc/source/user/plugins.rst
new file mode 100644
index 00000000..54d2dda5
--- /dev/null
+++ b/doc/source/user/plugins.rst
@@ -0,0 +1,51 @@
+==========================
+Writing custom check rules
+==========================
+
+oslo.policy has supported the following syntax for a while::
+
+    http:<target URL>, which delegates the check to a remote server
+
+
+Starting with 1.29, oslo.policy will also support https url(s) as well::
+
+    https:<target URL>, which delegates the check to a remote server
+
+
+Both ``http`` and ``https`` support are implemented as custom check rules.
+If you see the setup.cfg for oslo.policy, you can see the following
+entry points::
+
+    oslo.policy.rule_checks =
+        http = oslo_policy._external:HttpCheck
+        https = oslo_policy._external:HttpsCheck
+
+When a policy is evaluated, when the engine encounters ``https`` like in
+a snippet below::
+
+    {
+           ...
+           "target 1" : "https://foo.bar/baz",
+           ...
+    }
+
+The engine will look for a plugin named ``https`` in the ``rule_checks``
+entry point and will try to invoke that stevedore plugin.
+
+This mechanism allows anyone to write their own code, in their own library
+with their own custom stevedore based rule check plugins and can enhance
+their policies with custom checks. This would be useful for example to
+integrate with a in-house policy server.
+
+
+Example code - HttpCheck
+========================
+
+.. note::
+
+    Full source located at :example:`_external.py`
+
+.. literalinclude:: ../../../oslo_policy/_external.py
+    :language: python
+    :linenos:
+    :lines: 28-64
\ No newline at end of file
diff --git a/releasenotes/notes/add_custom_rule_check_plugins-3c15c2c7ca5e.yaml b/releasenotes/notes/add_custom_rule_check_plugins-3c15c2c7ca5e.yaml
new file mode 100644
index 00000000..d6b6121d
--- /dev/null
+++ b/releasenotes/notes/add_custom_rule_check_plugins-3c15c2c7ca5e.yaml
@@ -0,0 +1,6 @@
+---
+features:
+  - |
+    Add support for custom rule check plugins. ``http`` and ``https``
+    external rule checks have been converted into stevedore plugins and
+    serve as examples.
\ No newline at end of file