- Remove duplication of add_route API documentation from URL Disp…

…atch

  narrative chapter.

docs/narr/urldispatch.rst

@@ -385,207 +385,21 @@ Route Configuration Arguments
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Route configuration ``add_route`` statements may specify a large number of
-arguments.
+arguments.  They are documented as part of the API documentation at
+:meth:`pyramid.config.Configurator.add_route`.
 
 Many of these arguments are :term:`route predicate` arguments.  A route
 predicate argument specifies that some aspect of the request must be true for
 the associated route to be considered a match during the route matching
-process.
+process.  Examples of route predicate arguments are ``pattern``, ``xhr``, and
+``request_method``.
 
 Other arguments are view configuration related arguments.  These only have an
 effect when the route configuration names a ``view``.
 
 Other arguments are ``name`` and ``factory``.  These arguments represent
 neither predicates nor view configuration information.
 
-**Non-Predicate Arguments**
-
-``name``
-  The name of the route, e.g. ``myroute``.  This attribute is required.  It
-  must be unique among all defined routes in a given application.
-
-``factory``
-  A Python object (often a function or a class) or a :term:`dotted Python
-  name` to such an object that will generate a :app:`Pyramid` resource object
-  as the :term:`root` when this route matches. For example,
-  ``mypackage.resources.MyFactoryClass``.  If this argument is not specified,
-  the traversal root factory will be used.
-
-``traverse``
-  If you would like to cause the :term:`context` resource to be something
-  other than the :term:`root` resource object when this route matches, you
-  can spell a traversal pattern as the ``traverse`` argument.  This traversal
-  pattern will be used as the traversal path: traversal will begin at the
-  root object implied by this route (either the global root, or the object
-  returned by the ``factory`` associated with this route).
-
-  The syntax of the ``traverse`` argument is the same as it is for
-  ``pattern``. For example, if the ``pattern`` provided is
-  ``articles/{article}/edit``, and the ``traverse`` argument provided is
-  ``/{article}``, when a request comes in that causes the route to match in
-  such a way that the ``article`` match value is '1' (when the request URI is
-  ``/articles/1/edit``), the traversal path will be generated as ``/1``.
-  This means that the root object's ``__getitem__`` will be called with the
-  name ``1`` during the traversal phase.  If the ``1`` object exists, it will
-  become the :term:`context` resource of the request.
-  :ref:`traversal_chapter` has more information about traversal.
-
-  If the traversal path contains segment marker names which are not present
-  in the ``pattern`` argument, a runtime error will occur.  The ``traverse``
-  pattern should not contain segment markers that do not exist in the
-  ``pattern``.
-
-  A similar combining of routing and traversal is available when a route is
-  matched which contains a ``*traverse`` remainder marker in its pattern (see
-  :ref:`using_traverse_in_a_route_pattern`).  The ``traverse`` argument
-  allows you to associate route patterns with an arbitrary traversal path
-  without using a ``*traverse`` remainder marker; instead you can use other
-  match information.
-
-  Note that the ``traverse`` argument is ignored when attached to a route
-  that has a ``*traverse`` remainder marker in its pattern.
-
-**Predicate Arguments**
-
-``pattern``
-  The path of the route e.g. ``ideas/{idea}``.  This argument is required.
-  See :ref:`route_pattern_syntax` for information about the syntax of
-  route paths.  If the path doesn't match the current URL, route matching
-  continues.
-
-  .. note:: In earlier releases of this framework, this argument existed
-     as ``path``.  ``path`` continues to work as an alias for
-     ``pattern``.
-
-``xhr``
-  This value should be either ``True`` or ``False``.  If this value is
-  specified and is ``True``, the :term:`request` must possess an
-  ``HTTP_X_REQUESTED_WITH`` (aka ``X-Requested-With``) header for this route
-  to match.  This is useful for detecting AJAX requests issued from jQuery,
-  Prototype and other Javascript libraries.  If this predicate returns
-  ``False``, route matching continues.
-
-``request_method``
-  A string representing an HTTP method name, e.g. ``GET``, ``POST``,
-  ``HEAD``, ``DELETE``, ``PUT``.  If this argument is not specified, this
-  route will match if the request has *any* request method.  If this
-  predicate returns ``False``, route matching continues.
-
-``path_info``
-  This value represents a regular expression pattern that will be tested
-  against the ``PATH_INFO`` WSGI environment variable.  If the regex matches,
-  this predicate will return ``True``.  If this predicate returns ``False``,
-  route matching continues.
-
-``request_param``
-  This value can be any string.  A view declaration with this argument
-  ensures that the associated route will only match when the request has a
-  key in the ``request.params`` dictionary (an HTTP ``GET`` or ``POST``
-  variable) that has a name which matches the supplied value.  If the value
-  supplied as the argument has a ``=`` sign in it,
-  e.g. ``request_params="foo=123"``, then the key (``foo``) must both exist
-  in the ``request.params`` dictionary, and the value must match the right
-  hand side of the expression (``123``) for the route to "match" the current
-  request.  If this predicate returns ``False``, route matching continues.
-
-``header``
-  This argument represents an HTTP header name or a header name/value pair.
-  If the argument contains a ``:`` (colon), it will be considered a
-  name/value pair (e.g. ``User-Agent:Mozilla/.*`` or ``Host:localhost``).  If
-  the value contains a colon, the value portion should be a regular
-  expression.  If the value does not contain a colon, the entire value will
-  be considered to be the header name (e.g. ``If-Modified-Since``).  If the
-  value evaluates to a header name only without a value, the header specified
-  by the name must be present in the request for this predicate to be true.
-  If the value evaluates to a header name/value pair, the header specified by
-  the name must be present in the request *and* the regular expression
-  specified as the value must match the header value.  Whether or not the
-  value represents a header name or a header name/value pair, the case of the
-  header name is not significant.  If this predicate returns ``False``, route
-  matching continues.
-
-``accept``
-  This value represents a match query for one or more mimetypes in the
-  ``Accept`` HTTP request header.  If this value is specified, it must be in
-  one of the following forms: a mimetype match token in the form
-  ``text/plain``, a wildcard mimetype match token in the form ``text/*`` or a
-  match-all wildcard mimetype match token in the form ``*/*``.  If any of the
-  forms matches the ``Accept`` header of the request, this predicate will be
-  true.  If this predicate returns ``False``, route matching continues.
-
-``custom_predicates``
-  This value should be a sequence of references to custom predicate
-  callables.  Use custom predicates when no set of predefined predicates does
-  what you need.  Custom predicates can be combined with predefined
-  predicates as necessary.  Each custom predicate callable should accept two
-  arguments: ``info`` and ``request`` and should return either ``True`` or
-  ``False`` after doing arbitrary evaluation of the context resource and/or
-  the request.  If all callables return ``True``, the associated route will
-  be considered viable for a given request.  If any custom predicate returns
-  ``False``, route matching continues.  See :ref:`custom_route_predicates`
-  for more information.
-
-**View-Related Arguments**
-
-``view``
-  A Python object or a :term:`dotted Python name` to such an object that will
-  be used as a view callable when this route
-  matches. e.g. ``mypackage.views.my_view``.
-
-``view_context``
-  A class or an :term:`interface` (or a :term:`dotted Python name` to such an
-  object) that the :term:`context` resource should possess for the view named
-  by the route to be used.  If this attribute is not specified, the default
-  (``None``) will be used.
-
-  If the ``view`` argument is not provided, this argument has no effect.
-
-  This attribute can also be spelled as ``for_`` or ``view_for``.
-
-``view_permission``
-  The permission name required to invoke the view associated with this route.
-  e.g. ``edit``. (see :ref:`using_security_with_urldispatch` for more
-  information about permissions).
-
-  If the ``view`` attribute is not provided, this argument has no effect.
-
-  This argument can also be spelled as ``permission``.
-
-``view_renderer``
-  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``).  If the
-  renderer value is a single term (does not contain a dot ``.``), the
-  specified term will be used to look up a renderer implementation, and that
-  renderer implementation will be used to construct a response from the view
-  return value.  If the renderer term contains a dot (``.``), the specified
-  term will be treated as a path, and the filename extension of the last
-  element in the path will be used to look up the renderer implementation,
-  which will be passed the full path.  The renderer implementation will be
-  used to construct a response from the view return value.  See
-  :ref:`views_which_use_a_renderer` for more information.
-
-  If the ``view`` argument is not provided, this argument has no effect.
-
-  This argument can also be spelled as ``renderer``.
-
-``view_attr``
-  The view machinery defaults to using the ``__call__`` method of the view
-  callable (or the function itself, if the view callable is a function) to
-  obtain a response dictionary.  The ``attr`` value allows you to vary the
-  method attribute used to obtain the response.  For example, if your view
-  was a class, and the class has a method named ``index`` and you wanted to
-  use this method instead of the class' ``__call__`` method to return the
-  response, you'd say ``attr="index"`` in the view configuration for the
-  view.  This is most useful when the view definition is a class.
-
-  If the ``view`` argument is not provided, this argument has no
-  effect.
-
-``use_global_views``
-  When a request matches this route, and view lookup cannot find a view which
-  has a 'route_name' predicate argument that matches the route, try to fall
-  back to using a view that otherwise matches the context and request.
-
 .. _custom_route_predicates:
 
 Custom Route Predicates