Convert doctests in 'zope.security.zcml' into Sphinx doctest snppets.

They are still tested under 'tox -e docs'.

2 files changed, 63 insertions, 1 deletions

diff --git a/docs/api/zcml.rst b/docs/api/zcml.rst
new file mode 100644
index 0000000..dbf9179
--- /dev/null
+++ b/docs/api/zcml.rst
@@ -0,0 +1,62 @@
+:mod:`zope.security.zcml`
+===============================
+
+.. autoclass:: zope.security.zcml.Permission
+   :members:
+   :member-order: bysource
+
+Let's look at an example:
+
+.. doctest::
+
+   >>> from zope.security.zcml import Permission
+   >>> class FauxContext(object):
+   ...     permission_mapping = {'zope.ManageCode':'zope.private'}
+   ...     _actions = []
+   ...     def action(self, **kws):
+   ...        self._actions.append(kws)
+   >>> context = FauxContext()
+   >>> field = Permission().bind(context)
+
+Let's test the fromUnicode method:
+
+.. doctest::
+
+   >>> field.fromUnicode(u'zope.foo')
+   'zope.foo'
+   >>> field.fromUnicode(u'zope.ManageCode')
+   'zope.private'
+
+Now let's see whether validation works alright
+
+.. doctest::
+
+   >>> field._validate('zope.ManageCode')
+   >>> context._actions[0]['args']
+   (None, 'zope.foo')
+   >>> field._validate('3 foo')
+   Traceback (most recent call last):
+   ...
+   InvalidId: 3 foo
+
+   zope.Public is always valid
+   >>> field._validate('zope.Public')
+
+
+.. autointerface:: zope.security.zcml.ISecurityPolicyDirective
+   :members:
+   :member-order: bysource
+
+.. autofunction:: zope.security.zcml.securityPolicy
+
+.. autointerface:: zope.security.zcml.IPermissionDirective
+   :members:
+   :member-order: bysource
+
+.. autofunction:: zope.security.zcml.permission
+
+.. autointerface:: zope.security.zcml.IRedefinePermission
+   :members:
+   :member-order: bysource
+
+.. autofunction:: zope.security.zcml.redefinePermission
diff --git a/docs/index.rst b/docs/index.rst
index b928958..e99550d 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -17,7 +17,7 @@ API Reference
    api/proxy
    api/simplepolicies
    api/testing
-
+   api/zcml
 
 
 Indices and tables