- Garden PR #1121

12 files changed, 114 insertions, 43 deletions

diff --git a/docs/narr/advconfig.rst b/docs/narr/advconfig.rst
index d3431e39e..9ceaaa495 100644
--- a/docs/narr/advconfig.rst
+++ b/docs/narr/advconfig.rst
@@ -158,8 +158,12 @@ use :meth:`pyramid.config.Configurator.include`:
 Using :meth:`~pyramid.config.Configurator.include` instead of calling the
 function directly provides a modicum of automated conflict resolution, with
 the configuration statements you define in the calling code overriding those
-of the included function.  See also :ref:`automatic_conflict_resolution` and
-:ref:`including_configuration`.
+of the included function.
+
+.. seealso::
+
+    See also :ref:`automatic_conflict_resolution` and
+    :ref:`including_configuration`.
 
 Using ``config.commit()``
 +++++++++++++++++++++++++
diff --git a/docs/narr/environment.rst b/docs/narr/environment.rst
index f0c0c18fe..412635f08 100644
--- a/docs/narr/environment.rst
+++ b/docs/narr/environment.rst
@@ -59,8 +59,11 @@ third-party template rendering extensions.
 Reloading Assets
 ----------------
 
-Don't cache any asset file data when this value is true.  See
-also :ref:`overriding_assets_section`.
+Don't cache any asset file data when this value is true.
+
+.. seealso::
+
+    See also :ref:`overriding_assets_section`.
 
 +---------------------------------+-----------------------------+
 | Environment Variable Name       | Config File Setting Name    |
@@ -79,7 +82,11 @@ Debugging Authorization
 -----------------------
 
 Print view authorization failure and success information to stderr
-when this value is true.  See also :ref:`debug_authorization_section`.
+when this value is true.
+
+.. seealso::
+
+    See also :ref:`debug_authorization_section`.
 
 +---------------------------------+-----------------------------------+
 | Environment Variable Name       | Config File Setting Name          |
@@ -94,7 +101,11 @@ Debugging Not Found Errors
 --------------------------
 
 Print view-related ``NotFound`` debug messages to stderr
-when this value is true.  See also :ref:`debug_notfound_section`.
+when this value is true.
+
+.. seealso::
+
+    See also :ref:`debug_notfound_section`.
 
 +---------------------------------+------------------------------+
 | Environment Variable Name       | Config File Setting Name     |
@@ -109,7 +120,11 @@ Debugging Route Matching
 ------------------------
 
 Print debugging messages related to :term:`url dispatch` route matching when
-this value is true.  See also :ref:`debug_routematch_section`.
+this value is true.
+
+.. seealso::
+
+    See also :ref:`debug_routematch_section`.
 
 +---------------------------------+--------------------------------+
 | Environment Variable Name       | Config File Setting Name       |
@@ -128,7 +143,11 @@ Preventing HTTP Caching
 Prevent the ``http_cache`` view configuration argument from having any effect
 globally in this process when this value is true.  No http caching-related
 response headers will be set by the Pyramid ``http_cache`` view configuration
-feature when this is true.  See also :ref:`influencing_http_caching`.
+feature when this is true.
+
+.. seealso::
+
+    See also :ref:`influencing_http_caching`.
 
 +---------------------------------+----------------------------------+
 | Environment Variable Name       | Config File Setting Name         |
@@ -173,8 +192,11 @@ Default Locale Name
 --------------------
 
 The value supplied here is used as the default locale name when a
-:term:`locale negotiator` is not registered.  See also
-:ref:`localization_deployment_settings`.
+:term:`locale negotiator` is not registered.
+
+.. seealso::
+
+    See also :ref:`localization_deployment_settings`.
 
 +---------------------------------+-----------------------------------+
 | Environment Variable Name       | Config File Setting Name          |
diff --git a/docs/narr/events.rst b/docs/narr/events.rst
index 50484761d..09caac898 100644
--- a/docs/narr/events.rst
+++ b/docs/narr/events.rst
@@ -44,7 +44,7 @@ Configuring an Event Listener Imperatively
 You can imperatively configure a subscriber function to be called
 for some event type via the
 :meth:`~pyramid.config.Configurator.add_subscriber`
-method (see also :term:`Configurator`):
+method:
 
 .. code-block:: python
   :linenos:
@@ -63,6 +63,10 @@ The first argument to
 subscriber function (or a :term:`dotted Python name` which refers
 to a subscriber callable); the second argument is the event type.
 
+.. seealso::
+
+    See also :term:`Configurator`.
+
 Configuring an Event Listener Using a Decorator
 -----------------------------------------------
 
diff --git a/docs/narr/hellotraversal.rst b/docs/narr/hellotraversal.rst
index 142c24f54..0a93b8f16 100644
--- a/docs/narr/hellotraversal.rst
+++ b/docs/narr/hellotraversal.rst
@@ -60,10 +60,10 @@ A more complicated application could have many types of resources,
 with different view callables defined for each type, and even multiple
 views for each type.
 
-See Also
----------
+.. seealso::
 
-Full technical details may be found in :doc:`traversal`.
-
-For more about *why* you might use traversal, see :doc:`muchadoabouttraversal`.
+    Full technical details may be found in :doc:`traversal`.
+    
+    For more about *why* you might use traversal, see
+    :doc:`muchadoabouttraversal`.
 
diff --git a/docs/narr/introduction.rst b/docs/narr/introduction.rst
index 8acbab3a0..a37d74c9b 100644
--- a/docs/narr/introduction.rst
+++ b/docs/narr/introduction.rst
@@ -121,7 +121,9 @@ ways.
 
 .. literalinclude:: helloworld.py
 
-See also :ref:`firstapp_chapter`.
+.. seealso::
+
+    See also :ref:`firstapp_chapter`.
 
 Decorator-based configuration
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -271,7 +273,9 @@ Here's a few views defined as methods of a class instead:
        def view_two(self):
            return Response('two')
 
-See also :ref:`view_config_placement`.
+.. seealso::
+
+    See also :ref:`view_config_placement`.
 
 .. _intro_asset_specs:
 
@@ -572,7 +576,10 @@ For example:
       config.include('pyramid_exclog')
       config.include('some.other.guys.package', route_prefix='/someotherguy')
 
-See also :ref:`including_configuration` and :ref:`building_an_extensible_app`
+.. seealso::
+
+    See also :ref:`including_configuration` and
+    :ref:`building_an_extensible_app`.
 
 Flexible authentication and authorization
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -730,7 +737,9 @@ Pyramid defaults to explicit behavior, because it's the most generally
 useful, but provides hooks that allow you to adapt the framework to localized
 aesthetic desires.
 
-See also :ref:`using_iresponse`.
+.. seealso::
+
+    See also :ref:`using_iresponse`.
 
 "Global" response object
 ~~~~~~~~~~~~~~~~~~~~~~~~
@@ -748,7 +757,9 @@ section," you say.  Fine.  Be that way:
        response.content_type = 'text/plain'
        return response
 
-See also :ref:`request_response_attr`.
+.. seealso::
+
+    See also :ref:`request_response_attr`.
 
 Automating repetitive configuration
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -811,7 +822,9 @@ it up and calling :meth:`~pyramid.config.Configurator.add_directive` from
 within a function called when another user uses the
 :meth:`~pyramid.config.Configurator.include` method against your code.
 
-See also :ref:`add_directive`.
+.. seealso::
+
+    See also :ref:`add_directive`.
 
 Programmatic Introspection
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -839,7 +852,9 @@ callable:
         route_intr = introspector.get('routes', route_name)
         return Response(str(route_intr['pattern']))
 
-See also :ref:`using_introspection`.
+.. seealso::
+
+    See also :ref:`using_introspection`.
 
 Python 3 Compatibility
 ~~~~~~~~~~~~~~~~~~~~~~
diff --git a/docs/narr/project.rst b/docs/narr/project.rst
index eb12f67ef..62b91de0e 100644
--- a/docs/narr/project.rst
+++ b/docs/narr/project.rst
@@ -898,15 +898,22 @@ returns the HTML in a :term:`response`.
      a server restart to reload them.  Production applications should use
      ``pyramid.reload_templates = False``.
 
-.. seealso:: See also :ref:`views_which_use_a_renderer` for more information
+.. seealso::
+
+    See also :ref:`views_which_use_a_renderer` for more information
     about how views, renderers, and templates relate and cooperate.
 
-.. seealso:: Pyramid can also dynamically reload changed Python files.  For
-    more on this see :ref:`reloading_code`.
+.. seealso::
+
+    Pyramid can also dynamically reload changed Python files.  See also
+    :ref:`reloading_code`.
+
+.. seealso::
 
-.. seealso:: The :ref:`debug_toolbar` provides interactive access to your
-   application's internals and, should an exception occur, allows interactive
-   access to traceback execution stack frames from the Python interpreter.
+    See also the :ref:`debug_toolbar`, which provides interactive access to
+    your application's internals and, should an exception occur, allows
+    interactive access to traceback execution stack frames from the Python
+    interpreter.
 
 .. index::
    single: static directory
diff --git a/docs/narr/resources.rst b/docs/narr/resources.rst
index f3ff1dc4c..6139154ff 100644
--- a/docs/narr/resources.rst
+++ b/docs/narr/resources.rst
@@ -673,8 +673,11 @@ Calling ``find_interface(b, Thing2)`` will return the ``b`` resource.
 The second argument to find_interface may also be a :term:`interface` instead
 of a class.  If it is an interface, each resource in the lineage is checked
 to see if the resource implements the specificed interface (instead of seeing
-if the resource is of a class).  See also
-:ref:`resources_which_implement_interfaces`.
+if the resource is of a class).
+
+.. seealso::
+
+    See also :ref:`resources_which_implement_interfaces`.
 
 .. index::
    single: resource API functions
diff --git a/docs/narr/security.rst b/docs/narr/security.rst
index 9e6fb6c82..8db23a33b 100644
--- a/docs/narr/security.rst
+++ b/docs/narr/security.rst
@@ -113,9 +113,11 @@ authorization policies, it is an error to configure a Pyramid application
 with an authentication policy but without the authorization policy or vice
 versa.  If you do this, you'll receive an error at application startup time.
 
-See also the :mod:`pyramid.authorization` and
-:mod:`pyramid.authentication` modules for alternate implementations
-of authorization and authentication policies.  
+.. seealso::
+
+    See also the :mod:`pyramid.authorization` and
+    :mod:`pyramid.authentication` modules for alternate implementations of
+    authorization and authentication policies.
 
 .. index::
    single: permissions
@@ -495,8 +497,14 @@ is said to be *location-aware*.  Location-aware objects define an
 ``__parent__`` attribute which points at their parent object.  The
 root object's ``__parent__`` is ``None``.
 
-See :ref:`location_module` for documentations of functions which use
-location-awareness.  See also :ref:`location_aware`.
+.. seealso::
+
+    See also :ref:`location_module` for documentations of functions which use
+    location-awareness.
+
+.. seealso::
+
+    See also :ref:`location_aware`.
 
 .. index::
    single: forbidden view
diff --git a/docs/narr/templates.rst b/docs/narr/templates.rst
index 00fc21634..038dd2594 100644
--- a/docs/narr/templates.rst
+++ b/docs/narr/templates.rst
@@ -320,7 +320,11 @@ template renderer:
    in Chameleon, not in Mako templates.
 
 Similar renderer configuration can be done imperatively.  See
-:ref:`views_which_use_a_renderer`.  See also :ref:`built_in_renderers`.
+:ref:`views_which_use_a_renderer`.
+
+.. seealso::
+
+    See also :ref:`built_in_renderers`.
 
 Although a renderer path is usually just a simple relative pathname, a path
 named as a renderer can be absolute, starting with a slash on UNIX or a drive
diff --git a/docs/narr/testing.rst b/docs/narr/testing.rst
index 5a5bf8fad..e001ad81c 100644
--- a/docs/narr/testing.rst
+++ b/docs/narr/testing.rst
@@ -319,8 +319,10 @@ registering resources at paths, registering event listeners, registering
 views and view permissions, and classes representing "dummy" implementations
 of a request and a resource.
 
-See also the various methods of the :term:`Configurator` documented in
-:ref:`configuration_module` that begin with the ``testing_`` prefix.
+.. seealso::
+
+    See also the various methods of the :term:`Configurator` documented in
+    :ref:`configuration_module` that begin with the ``testing_`` prefix.
 
 .. index::
    single: integration tests
diff --git a/docs/narr/urldispatch.rst b/docs/narr/urldispatch.rst
index 96ee5758e..87a962a9a 100644
--- a/docs/narr/urldispatch.rst
+++ b/docs/narr/urldispatch.rst
@@ -1183,9 +1183,10 @@ still easily do it by wrapping it in classmethod call.
 Same will work with staticmethod, just use ``staticmethod`` instead of
 ``classmethod``.
 
+.. seealso::
 
-See also :class:`pyramid.interfaces.IRoute` for more API documentation about
-route objects.
+    See also :class:`pyramid.interfaces.IRoute` for more API documentation
+    about route objects.
 
 .. index::
    single: route factory
diff --git a/docs/narr/viewconfig.rst b/docs/narr/viewconfig.rst
index 84fde3f01..adc53bd11 100644
--- a/docs/narr/viewconfig.rst
+++ b/docs/narr/viewconfig.rst
@@ -118,8 +118,9 @@ Non-Predicate Arguments
 
 ``renderer``
   Denotes the :term:`renderer` implementation which will be used to construct
-  a :term:`response` from the associated view callable's return value. (see
-  also :ref:`renderers_chapter`).
+  a :term:`response` from the associated view callable's return value.
+  
+  .. seealso:: See also :ref:`renderers_chapter`.
 
   This is either a single string term (e.g. ``json``) or a string implying a
   path or :term:`asset specification` (e.g. ``templates/views.pt``) naming a