Merge pull request #1241 from stevepiercy/master

Garden Sphinx directives

docs/api/registry.rst

@@ -21,7 +21,10 @@
      When a registry is set up (or created) by a :term:`Configurator`, the
      registry will be decorated with an instance named ``introspector``
      implementing the :class:`pyramid.interfaces.IIntrospector` interface.
-     See also :attr:`pyramid.config.Configurator.introspector`.
+
+     .. seealso::
+
+        See also :attr:`pyramid.config.Configurator.introspector`.
 
      When a registry is created "by hand", however, this attribute will not
      exist until set up by a configurator.

docs/api/request.rst

@@ -250,8 +250,11 @@
       ``invoke_subrequest`` isn't *actually* a method of the Request object;
       it's a callable added when the Pyramid router is invoked, or when a
       subrequest is invoked.  This means that it's not available for use on a
-      request provided by e.g. the ``pshell`` environment.  For more
-      information, see :ref:`subrequest_chapter`.
+      request provided by e.g. the ``pshell`` environment.
+
+      .. seealso::
+
+          See also :ref:`subrequest_chapter`.
 
    .. automethod:: has_permission
 
@@ -280,7 +283,11 @@
        This property will return the JSON-decoded variant of the request
        body.  If the request body is not well-formed JSON, or there is no
        body associated with this request, this property will raise an
-       exception.  See also :ref:`request_json_body`.
+       exception.
+
+       .. seealso::
+
+           See also :ref:`request_json_body`.
 
    .. method:: set_property(callable, name=None, reify=False)
 

docs/designdefense.rst

@@ -537,7 +537,11 @@ text indexing.  It does not dictate how you arrange your code.
 
 Such opinionated functionality exists in applications and frameworks built
 *on top* of :app:`Pyramid`.  It's intended that higher-level systems emerge
-built using :app:`Pyramid` as a base.  See also :ref:`apps_are_extensible`.
+built using :app:`Pyramid` as a base.
+
+.. seealso::
+
+    See also :ref:`apps_are_extensible`.
 
 Pyramid Provides Too Many "Rails"
 ---------------------------------

docs/glossary.rst

@@ -54,8 +54,12 @@ Glossary
      provides an API for addressing "asset files" within a Python
      :term:`package`.  Asset files are static files, template files, etc;
      basically anything non-Python-source that lives in a Python package can
-     be considered a asset file.  See also `PkgResources
-     <http://peak.telecommunity.com/DevCenter/PkgResources>`_
+     be considered a asset file.
+
+     .. seealso::
+
+         See also `PkgResources
+         <http://peak.telecommunity.com/DevCenter/PkgResources>`_.
 
    asset
      Any file contained within a Python :term:`package` which is *not*
@@ -242,7 +246,11 @@ Glossary
      be effectively amended with a ``permission`` argument that will
      require that the executing user possess the default permission in
      order to successfully execute the associated :term:`view
-     callable` See also :ref:`setting_a_default_permission`.
+     callable`.
+
+     .. seealso::
+
+        See also :ref:`setting_a_default_permission`.
 
    ACE
      An *access control entry*.  An access control entry is one element
@@ -380,7 +388,11 @@ Glossary
    route
      A single pattern matched by the :term:`url dispatch` subsystem,
      which generally resolves to a :term:`root factory` (and then
-     ultimately a :term:`view`).  See also :term:`url dispatch`.
+     ultimately a :term:`view`).
+
+     .. seealso::
+
+        See also :term:`url dispatch`.
 
    route configuration
      Route configuration is the act of associating request parameters with a
@@ -580,8 +592,11 @@ Glossary
      A wrapper around a Python function or class which accepts the
      function or class as its first argument and which returns an
      arbitrary object.  :app:`Pyramid` provides several decorators,
-     used for configuration and return value modification purposes.  See
-     also `PEP 318 <http://www.python.org/dev/peps/pep-0318/>`_.
+     used for configuration and return value modification purposes.
+
+     .. seealso::
+
+        See also `PEP 318 <http://www.python.org/dev/peps/pep-0318/>`_.
 
    configuration declaration
      An individual method call made to a :term:`configuration directive`,
@@ -646,8 +661,11 @@ Glossary
    HTTP Exception
       The set of exception classes defined in :mod:`pyramid.httpexceptions`.
       These can be used to generate responses with various status codes when
-      raised or returned from a :term:`view callable`.  See also
-      :ref:`http_exceptions`.
+      raised or returned from a :term:`view callable`.
+
+      .. seealso::
+
+          See also :ref:`http_exceptions`.
 
    thread local
       A thread-local variable is one which is essentially a global variable
@@ -656,8 +674,11 @@ Glossary
       application may have a different value for this same "global" variable.
       :app:`Pyramid` uses a small number of thread local variables, as
       described in :ref:`threadlocals_chapter`.
-      See also the :class:`stdlib documentation <threading.local>`
-      for more information.
+
+      .. seealso::
+
+          See also the :class:`stdlib documentation <threading.local>`
+          for more information.
 
    multidict
      An ordered dictionary that can have multiple values for each key. Adds
@@ -671,7 +692,11 @@ Glossary
 
    Agendaless Consulting
      A consulting organization formed by Paul Everitt, Tres Seaver,
-     and Chris McDonough.  See also http://agendaless.com .
+     and Chris McDonough.
+
+     .. seealso::
+
+         See also `Agendaless Consulting <http://agendaless.com>`_.
 
    Jython
      A `Python implementation <http://www.jython.org/>`_ written for
@@ -792,15 +817,21 @@ Glossary
      The act of creating software with a user interface that can
      potentially be displayed in more than one language or cultural
      context.  Often shortened to "i18n" (because the word
-     "internationalization" is I, 18 letters, then N).  See also:
-     :term:`Localization`.
+     "internationalization" is I, 18 letters, then N).
+
+     .. seealso::
+
+         See also :term:`Localization`.
 
    Localization
      The process of displaying the user interface of an
      internationalized application in a particular language or
      cultural context.  Often shortened to "l10" (because the word
-     "localization" is L, 10 letters, then N).  See also:
-     :term:`Internationalization`.
+     "localization" is L, 10 letters, then N).
+
+     .. seealso::
+
+         See also :term:`Internationalization`.
 
    renderer globals
       Values injected as names into a renderer by a
@@ -809,7 +840,10 @@ Glossary
    response callback
       A user-defined callback executed by the :term:`router` at a
       point after a :term:`response` object is successfully created.
-      See :ref:`using_response_callbacks`.
+
+      .. seealso::
+
+          See also :ref:`using_response_callbacks`.
 
    finished callback
       A user-defined callback executed by the :term:`router`

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()``
 +++++++++++++++++++++++++

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          |

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
 -----------------------------------------------
 

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`.
 

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
 ~~~~~~~~~~~~~~~~~~~~~~