docs fixes

Chris McDonough

2012-02-17 0a6a26ca36f6aff7d03b438eef57f6b8d17123e9

docs fixes

 docs/narr/resources.rst

@@ -303,13 +303,22 @@
two keys:

``physical_path``
   The "physical path" computed for the resource, as defined by
   ``pyramid.traversal.resource_path(resource)``.
   A string representing the "physical path" computed for the resource, as
   defined by ``pyramid.traversal.resource_path(resource)``.  It will begin
   and end with a slash.

``virtual_path``
   The "virtual path" computed for the resource, as defined by
   :ref:`virtual_root_support`.  This will be identical to the physical path
   if virtual rooting is not enabled.
   A string representing the "virtual path" computed for the resource, as
   defined by :ref:`virtual_root_support`.  This will be identical to the
   physical path if virtual rooting is not enabled.  It will begin and end
   with a slash.

``app_url``
  A string representing the application URL generated during
  ``request.resource_url``.  It will not end with a slash.  It represents a
  potentially customized URL prefix, containing potentially custom scheme,
  host and port information passed by the user to ``request.resource_url``.
  It should be preferred over use of ``request.application_url``.

The ``__resource_url__`` method of a resource should return a string
representing a URL.  If it cannot override the default, it should return
@@ -322,16 +331,16 @@

   class Resource(object):
       def __resource_url__(self, request, info):
           return request.application_url + info['virtual_path']
           return info['app_url'] + info['virtual_path']

The above example actually just generates and returns the default URL, which
would have been what was returned anyway, but your code can perform arbitrary
logic as necessary.  For example, your code may wish to override the hostname
or port number of the generated URL.
would have been what was generated by the default ``resource_url`` machinery,
but your code can perform arbitrary logic as necessary.  For example, your
code may wish to override the hostname or port number of the generated URL.

Note that the URL generated by ``__resource_url__`` should be fully
qualified, should end in a slash, and should not contain any query string or
anchor elements (only path elements) to work best with
anchor elements (only path elements) to work with
:meth:`~pyramid.request.Request.resource_url`.

.. index::

 docs/whatsnew-1.3.rst

@@ -274,7 +274,7 @@
  ``ignore`` argument, which can be a string, a callable, or a list
  consisting of strings and/or callables.  This feature allows submodules,
  subpackages, and global objects from being scanned.  See
   http://readthedocs.org/docs/venusian/en/latest/#ignore-scan-argument for
  http://readthedocs.org/docs/venusian/en/latest/#ignore-scan-argument for
  more information about how to use the ``ignore`` argument to ``scan``.

- Better error messages when a view callable returns a value that cannot be

 pyramid/url.py

@@ -160,13 +160,18 @@
        element will always follow the query element,
        e.g. ``http://example.com?foo=1#bar``.

        If any of ``_scheme``, ``_host``, or ``_port`` is passed and is
        non-``None``, the provided value will replace the named portion in
        the generated URL.  If ``_scheme`` is passed as ``https``, and
        If any of the keyword arguments ``_scheme``, ``_host``, or ``_port``
        is passed and is non-``None``, the provided value will replace the
        named portion in the generated URL.  For example, if you pass
        ``_host='foo.com'``, and the URL that would have been generated
        without the host replacement is ``http://example.com/a``, the result
        will be ``https://foo.com/a``.
        
        Note that if ``_scheme`` is passed as ``https``, and ``_port`` is not
        passed, the ``_port`` value is assumed to have been passed as
        ``443``.  Likewise, if ``_scheme`` is passed as ``http`` and
        ``_port`` is not passed, the ``_port`` value is assumed to have been
        passed as ``443``.  Likewise, if ``_scheme`` is passed as ``http``
        and ``_port`` is not passed, the ``_port`` value is assumed to have
        been passed as ``80``. To avoid this behavior, always explicitly pass
        passed as ``80``. To avoid this behavior, always explicitly pass
        ``_port`` whenever you pass ``_scheme``.

        If a keyword ``_app_url`` is present, it will be used as the
@@ -362,9 +367,9 @@
        If any of the keyword arguments ``scheme``, ``host``, or ``port`` is
        passed and is non-``None``, the provided value will replace the named
        portion in the generated URL.  For example, if you pass
        ``scheme='https'``, and the URL that would be generated without the
        scheme replacement is ``http://foo.com``, the result will be
        ``https://foo.com``.
        ``host='foo.com'``, and the URL that would have been generated
        without the host replacement is ``http://example.com/a``, the result
        will be ``https://foo.com/a``.
        
        If ``scheme`` is passed as ``https``, and an explicit ``port`` is not
        passed, the ``port`` value is assumed to have been passed as ``443``.