Apply drafting changes to documentation.

8 files changed, 41 insertions, 29 deletions

diff --git a/CHANGES.txt b/CHANGES.txt
index 9d6264688..762550053 100644
--- a/CHANGES.txt
+++ b/CHANGES.txt
@@ -25,7 +25,7 @@ Features
   appropriately. See https://github.com/Pylons/pyramid/pull/2989
 
 - A new CSRF implementation, :class:`pyramid.csrf.SessionCSRF` has been added,
-  which deleagates all CSRF generation to the current session, following the
+  which delegates all CSRF generation to the current session, following the
   old API for this. A ``get_csrf_token()`` method is now available in template
   global scope, to make it easy for template developers to get the current CSRF
   token without adding it to Python code.
diff --git a/docs/glossary.rst b/docs/glossary.rst
index 0a46fac3b..0cf96f488 100644
--- a/docs/glossary.rst
+++ b/docs/glossary.rst
@@ -891,6 +891,11 @@ Glossary
       :meth:`pyramid.config.Configurator.set_session_factory` for more
       information.
 
+   CSRF storage policy
+      A utility that implements :class:`pyramid.interfaces.ICSRFStoragePolicy`
+      which is responsible for allocating CSRF tokens to a user and verifying
+      that a provided token is acceptable.
+
    Mako
      `Mako <http://www.makotemplates.org/>`_ is a template language
      which refines the familiar ideas of componentized layout and inheritance
diff --git a/docs/narr/security.rst b/docs/narr/security.rst
index e67f7b98c..86e5c1ef4 100644
--- a/docs/narr/security.rst
+++ b/docs/narr/security.rst
@@ -766,6 +766,10 @@ a secret across two different subsystems might drop the security of signing to
 zero. Keys should not be re-used across different contexts where an attacker
 has the possibility of providing a chosen plaintext.
 
+.. index::
+   single: preventing cross-site request forgery attacks
+   single: cross-site request forgery attacks, prevention
+
 Preventing Cross-Site Request Forgery Attacks
 ---------------------------------------------
 
diff --git a/docs/narr/sessions.rst b/docs/narr/sessions.rst
index 86fe2a139..7e2469d54 100644
--- a/docs/narr/sessions.rst
+++ b/docs/narr/sessions.rst
@@ -315,7 +315,3 @@ flash storage.
    ['info message']
    >>> request.session.peek_flash()
    []
-
-.. index::
-   single: preventing cross-site request forgery attacks
-   single: cross-site request forgery attacks, prevention
diff --git a/pyramid/config/security.py b/pyramid/config/security.py
index 0b565e322..6f5b36d3a 100644
--- a/pyramid/config/security.py
+++ b/pyramid/config/security.py
@@ -232,7 +232,7 @@ class SecurityConfiguratorMixin(object):
     @action_method
     def set_csrf_storage_policy(self, policy):
         """
-        Set the CSRF storage policy used by subsequent view registrations.
+        Set the :term:`CSRF storage policy` used by subsequent view registrations.
 
         ``policy`` is a class that implements the
         :meth:`pyramid.interfaces.ICSRFStoragePolicy` interface that will be used for all
diff --git a/pyramid/config/views.py b/pyramid/config/views.py
index e037f7706..2fc243fac 100644
--- a/pyramid/config/views.py
+++ b/pyramid/config/views.py
@@ -651,6 +651,12 @@ class ViewsConfiguratorMixin(object):
 
           .. versionadded:: 1.4a2
 
+          .. versionchanged:: 1.9
+            This feature requires either a :term:`session factory` to have been
+            configured, or a :term:`CSRF storage policy` other than the default
+            to be in use.
+
+
         physical_path
 
           If specified, this value should be a string or a tuple representing
diff --git a/pyramid/csrf.py b/pyramid/csrf.py
index 4c5a73940..ffc7b5fe3 100644
--- a/pyramid/csrf.py
+++ b/pyramid/csrf.py
@@ -31,7 +31,7 @@ class SessionCSRFStoragePolicy(object):
     Note that using this CSRF implementation requires that
     a :term:`session factory` is configured.
 
-    .. versionadded :: 1.8a1
+    .. versionadded :: 1.9
     """
     def new_csrf_token(self, request):
         """ Sets a new CSRF token into the session and returns it. """
@@ -43,8 +43,8 @@ class SessionCSRFStoragePolicy(object):
         return request.session.get_csrf_token()
 
     def check_csrf_token(self, request, supplied_token):
-        """ Returns True if supplied_token is the same value as get_csrf_token
-        returns for this request. """
+        """ Returns ``True`` if ``supplied_token is`` the same value as
+        ``get_csrf_token(request)``."""
         expected = self.get_csrf_token(request)
         return not strings_differ(
             bytes_(expected, 'ascii'),
@@ -55,11 +55,11 @@ class SessionCSRFStoragePolicy(object):
 class CookieCSRFStoragePolicy(object):
     """ An alternative CSRF implementation that stores its information in
     unauthenticated cookies, known as the 'Double Submit Cookie' method in the
-    OWASP CSRF guidelines. This gives some additional flexibility with regards
-    to scaling as the tokens can be generated and verified by a front-end
-    server.
+    `OWASP CSRF guidelines <https://www.owasp.org/index.php/Cross-Site_Request_Forgery_(CSRF)_Prevention_Cheat_Sheet#Double_Submit_Cookie>`_.
+    This gives some additional flexibility with regards to scaling as the tokens
+    can be generated and verified by a front-end server.
 
-    .. versionadded :: 1.8a1
+    .. versionadded :: 1.9
     """
 
     def __init__(self, cookie_name='csrf_token', secure=False, httponly=False,
@@ -96,8 +96,8 @@ class CookieCSRFStoragePolicy(object):
         return token
 
     def check_csrf_token(self, request, supplied_token):
-        """ Returns True if supplied_token is the same value as get_csrf_token
-        returns for this request. """
+        """ Returns ``True`` if ``supplied_token is`` the same value as
+        ``get_csrf_token(request)``."""
         expected = self.get_csrf_token(request)
         return not strings_differ(
             bytes_(expected, 'ascii'),
@@ -109,7 +109,7 @@ def get_csrf_token(request):
     a new one using ``new_csrf_token(request)`` if one does not exist. This
     calls the equivalent method in the chosen CSRF protection implementation.
 
-    .. versionadded :: 1.8a1
+    .. versionadded :: 1.9
     """
     registry = request.registry
     csrf = registry.getUtility(ICSRFStoragePolicy)
@@ -121,7 +121,7 @@ def new_csrf_token(request):
     implementation defined manner. This calls the equivalent method in the
     chosen CSRF protection implementation.
 
-    .. versionadded :: 1.8a1
+    .. versionadded :: 1.9
     """
     registry = request.registry
     csrf = registry.getUtility(ICSRFStoragePolicy)
@@ -159,8 +159,8 @@ def check_csrf_token(request,
        considered valid. It must be passed in either the request body or
        a header.
 
-    .. versionchanged:: 1.8a1
-       Moved from pyramid.session to pyramid.csrf
+    .. versionchanged:: 1.9
+       Moved from :mod:`pyramid.session` to :mod:`pyramid.csrf`
     """
     supplied_token = ""
     # We first check the headers for a csrf token, as that is significantly
@@ -192,27 +192,28 @@ def check_csrf_token(request,
 
 def check_csrf_origin(request, trusted_origins=None, raises=True):
     """
-    Check the Origin of the request to see if it is a cross site request or
+    Check the ``Origin`` of the request to see if it is a cross site request or
     not.
 
-    If the value supplied by the Origin or Referer header isn't one of the
+    If the value supplied by the ``Origin`` or ``Referer`` header isn't one of the
     trusted origins and ``raises`` is ``True``, this function will raise a
-    :exc:`pyramid.exceptions.BadCSRFOrigin` exception but if ``raises`` is
-    ``False`` this function will return ``False`` instead. If the CSRF origin
+    :exc:`pyramid.exceptions.BadCSRFOrigin` exception, but if ``raises`` is
+    ``False``, this function will return ``False`` instead. If the CSRF origin
     checks are successful this function will return ``True`` unconditionally.
 
     Additional trusted origins may be added by passing a list of domain (and
-    ports if nonstandard like `['example.com', 'dev.example.com:8080']`) in
+    ports if nonstandard like ``['example.com', 'dev.example.com:8080']``) in
     with the ``trusted_origins`` parameter. If ``trusted_origins`` is ``None``
     (the default) this list of additional domains will be pulled from the
     ``pyramid.csrf_trusted_origins`` setting.
 
-    Note that this function will do nothing if request.scheme is not https.
+    Note that this function will do nothing if ``request.scheme`` is not
+    ``https``.
 
     .. versionadded:: 1.7
 
-    .. versionchanged:: 1.8a1
-       Moved from pyramid.session to pyramid.csrf
+    .. versionchanged:: 1.9
+       Moved from :mod:`pyramid.session` to :mod:`pyramid.csrf`
     """
     def _fail(reason):
         if raises:
diff --git a/pyramid/interfaces.py b/pyramid/interfaces.py
index aab5647a1..c3b6b164d 100644
--- a/pyramid/interfaces.py
+++ b/pyramid/interfaces.py
@@ -999,8 +999,8 @@ class ICSRFStoragePolicy(Interface):
         """
 
     def check_csrf_token(request, supplied_token):
-        """ Returns a boolean that represents if supplied_token is a valid CSRF
-        token for this request. Comparing strings for equality must be done
+        """ Returns a boolean that represents if ``supplied_token`` is a valid
+        CSRF token for this request. Comparing strings for equality must be done
         using :func:`pyramid.utils.strings_differ` to avoid timing attacks.
         """