security policy docs and legacy policy improvements

- Added `set_security_policy`` to more places in the docs.
- Ensure that the authn/authz policies are not used at all if the legacy
  policy is not in effect to avoid edge cases where the code would skip
  the security policy and use the authn/authz policy on accident.
- Change deprecation warnings in code to reference the docs by name
  instead of by URL.

1 files changed, 6 insertions, 6 deletions

diff --git a/docs/designdefense.rst b/docs/designdefense.rst
index 967a1aaed..0fa609aa1 100644
--- a/docs/designdefense.rst
+++ b/docs/designdefense.rst
@@ -199,11 +199,11 @@ Under its hood however, the implementation of ``authenticated_userid`` is this:
 
     def authenticated_userid(request):
         """ Return the userid of the currently authenticated user or
-        ``None`` if there is no authentication policy in effect or there
+        ``None`` if there is no security policy in effect or there
         is no currently authenticated user. """
 
         registry = request.registry # the ZCA component registry
-        policy = registry.queryUtility(IAuthenticationPolicy)
+        policy = registry.queryUtility(ISecurityPolicy)
         if policy is None:
             return None
         return policy.authenticated_userid(request)
@@ -264,19 +264,19 @@ instead of the rule.  So instead of:
 .. code-block:: python
     :linenos:
 
-    from pyramid.interfaces import IAuthenticationPolicy
+    from pyramid.interfaces import ISecurityPolicy
     from zope.component import getUtility
-    policy = getUtility(IAuthenticationPolicy)
+    policy = getUtility(ISecurityPolicy)
 
 :app:`Pyramid` code will usually do:
 
 .. code-block:: python
     :linenos:
 
-    from pyramid.interfaces import IAuthenticationPolicy
+    from pyramid.interfaces import ISecurityPolicy
     from pyramid.threadlocal import get_current_registry
     registry = get_current_registry()
-    policy = registry.getUtility(IAuthenticationPolicy)
+    policy = registry.getUtility(ISecurityPolicy)
 
 While the latter is more verbose, it also arguably makes it more obvious what's
 going on.  All of the :app:`Pyramid` core code uses this pattern rather than