From 012b9762cd0b114b6afbf2d6356554b51706804a Mon Sep 17 00:00:00 2001 From: michr Date: Fri, 23 Sep 2011 18:48:28 -0700 Subject: fixed up all the warning dealing ..note and ..warn added a hide toc for glossary to prevent warnings --- docs/narr/assets.rst | 8 ++++++-- docs/narr/hooks.rst | 16 ++++++++++++---- docs/narr/i18n.rst | 8 ++++++-- docs/narr/install.rst | 4 +++- docs/narr/logging.rst | 4 +++- docs/narr/muchadoabouttraversal.rst | 4 +++- docs/narr/project.rst | 4 +++- docs/narr/resources.rst | 4 +++- docs/narr/templates.rst | 4 +++- docs/narr/urldispatch.rst | 12 +++++++++--- 10 files changed, 51 insertions(+), 17 deletions(-) (limited to 'docs/narr') diff --git a/docs/narr/assets.rst b/docs/narr/assets.rst index 93b03fbc9..cd76f7b60 100644 --- a/docs/narr/assets.rst +++ b/docs/narr/assets.rst @@ -102,7 +102,9 @@ directory on a filesystem to an application user's browser. Use the mechanism makes a directory of static files available at a name relative to the application root URL, e.g. ``/static`` or as an external URL. -.. note:: :meth:`~pyramid.config.Configurator.add_static_view` cannot serve a +.. note:: + + :meth:`~pyramid.config.Configurator.add_static_view` cannot serve a single file, nor can it serve a directory of static files directly relative to the root URL of a :app:`Pyramid` application. For these features, see :ref:`advanced_static`. @@ -312,7 +314,9 @@ instance of this class is actually used by the :meth:`~pyramid.config.Configurator.add_static_view` configuration method, so its behavior is almost exactly the same once it's configured. -.. warning:: The following example *will not work* for applications that use +.. warning:: + + The following example *will not work* for applications that use :term:`traversal`, it will only work if you use :term:`URL dispatch` exclusively. The root-relative route we'll be registering will always be matched before traversal takes place, subverting any views registered via diff --git a/docs/narr/hooks.rst b/docs/narr/hooks.rst index 4afc0506b..3ab82ecf7 100644 --- a/docs/narr/hooks.rst +++ b/docs/narr/hooks.rst @@ -55,7 +55,9 @@ Here's some sample code that implements a minimal NotFound view callable: def notfound_view(request): return HTTPNotFound() -.. note:: When a NotFound view callable is invoked, it is passed a +.. note:: + + When a NotFound view callable is invoked, it is passed a :term:`request`. The ``exception`` attribute of the request will be an instance of the :exc:`~pyramid.httpexceptions.HTTPNotFound` exception that caused the not found view to be called. The value of @@ -64,7 +66,9 @@ Here's some sample code that implements a minimal NotFound view callable: ``pyramid.debug_notfound`` environment setting is true than it is when it is false. -.. warning:: When a NotFound view callable accepts an argument list as +.. warning:: + + When a NotFound view callable accepts an argument list as described in :ref:`request_and_context_view_definitions`, the ``context`` passed as the first argument to the view callable will be the :exc:`~pyramid.httpexceptions.HTTPNotFound` exception instance. If @@ -121,7 +125,9 @@ Here's some sample code that implements a minimal forbidden view: def forbidden_view(request): return Response('forbidden') -.. note:: When a forbidden view callable is invoked, it is passed a +.. note:: + + When a forbidden view callable is invoked, it is passed a :term:`request`. The ``exception`` attribute of the request will be an instance of the :exc:`~pyramid.httpexceptions.HTTPForbidden` exception that caused the forbidden view to be called. The value of @@ -1100,7 +1106,9 @@ in the ``pyramid.tweens`` list will be used as the producer of the effective declared directly "below" it, ad infinitum. The "main" Pyramid request handler is implicit, and always "at the bottom". -.. note:: Pyramid's own :term:`exception view` handling logic is implemented +.. note:: + + Pyramid's own :term:`exception view` handling logic is implemented as a tween factory function: :func:`pyramid.tweens.excview_tween_factory`. If Pyramid exception view handling is desired, and tween factories are specified via the ``pyramid.tweens`` configuration setting, the diff --git a/docs/narr/i18n.rst b/docs/narr/i18n.rst index aef9b59ab..bac86e982 100644 --- a/docs/narr/i18n.rst +++ b/docs/narr/i18n.rst @@ -518,7 +518,9 @@ negotiator is registered. def aview(request): locale = get_localizer(request) -.. note:: If you need to create a localizer for a locale use the +.. note:: + + If you need to create a localizer for a locale use the :func:`pyramid.i18n.make_localizer` function. .. index:: @@ -555,7 +557,9 @@ represented by the request. The translation returned from its ``domain`` attribute of the provided translation string as well as the locale of the localizer. -.. note:: If you're using :term:`Chameleon` templates, you don't need +.. note:: + + If you're using :term:`Chameleon` templates, you don't need to pre-translate translation strings this way. See :ref:`chameleon_translation_strings`. diff --git a/docs/narr/install.rst b/docs/narr/install.rst index a1e7ce382..e1b5eb208 100644 --- a/docs/narr/install.rst +++ b/docs/narr/install.rst @@ -229,7 +229,9 @@ following: New python executable in env/bin/python Installing setuptools.............done. -.. warning:: Using ``--no-site-packages`` when generating your +.. warning:: + + Using ``--no-site-packages`` when generating your virtualenv is *very important*. This flag provides the necessary isolation for running the set of packages required by :app:`Pyramid`. If you do not specify ``--no-site-packages``, diff --git a/docs/narr/logging.rst b/docs/narr/logging.rst index 8abcba3c7..3e39151a3 100644 --- a/docs/narr/logging.rst +++ b/docs/narr/logging.rst @@ -7,7 +7,9 @@ Logging :mod:`logging` module. This chapter describes how to configure logging and how to send log messages to loggers that you've configured. -.. warning:: This chapter assumes you've used a :term:`scaffold` to create a +.. warning:: + + This chapter assumes you've used a :term:`scaffold` to create a project which contains ``development.ini`` and ``production.ini`` files which help configure logging. All of the scaffolds which ship along with :app:`Pyramid` do this. If you're not using a scaffold, or if you've used diff --git a/docs/narr/muchadoabouttraversal.rst b/docs/narr/muchadoabouttraversal.rst index 6ad33c1ce..a948e57cc 100644 --- a/docs/narr/muchadoabouttraversal.rst +++ b/docs/narr/muchadoabouttraversal.rst @@ -313,6 +313,8 @@ don't require it, great: stick with :term:`URL dispatch`. But if you're using :app:`Pyramid` and you ever find that you *do* need to support one of these use cases, you'll be glad you have traversal in your toolkit. -.. note:: It is even possible to mix and match :term:`traversal` with +.. note:: + + It is even possible to mix and match :term:`traversal` with :term:`URL dispatch` in the same :app:`Pyramid` application. See the :ref:`hybrid_chapter` chapter for details. diff --git a/docs/narr/project.rst b/docs/narr/project.rst index 10b7a5d04..345672204 100644 --- a/docs/narr/project.rst +++ b/docs/narr/project.rst @@ -64,7 +64,9 @@ The included scaffolds are these: URL mapping via :term:`traversal` and persistence via :term:`SQLAlchemy` -.. note:: At this time, each of these scaffolds uses the :term:`Chameleon` +.. note:: + + At this time, each of these scaffolds uses the :term:`Chameleon` templating system, which is incompatible with Jython. To use scaffolds to build applications which will run on Jython, you can try the ``pyramid_jinja2_starter`` scaffold which ships as part of the diff --git a/docs/narr/resources.rst b/docs/narr/resources.rst index b8dc6d857..256f69fc3 100644 --- a/docs/narr/resources.rst +++ b/docs/narr/resources.rst @@ -160,7 +160,9 @@ resource in the resource tree, you will eventually come to the root resource, just like if you keep executing the ``cd ..`` filesystem command, eventually you will reach the filesystem root directory. -.. warning:: If your root resource has a ``__name__`` argument that is not +.. warning:: + + If your root resource has a ``__name__`` argument that is not ``None`` or the empty string, URLs returned by the :func:`~pyramid.request.Request.resource_url` function and paths generated by the :func:`~pyramid.traversal.resource_path` and diff --git a/docs/narr/templates.rst b/docs/narr/templates.rst index 6412c070d..052843a23 100644 --- a/docs/narr/templates.rst +++ b/docs/narr/templates.rst @@ -46,7 +46,9 @@ within the body of a view callable like so: {'foo':1, 'bar':2}, request=request) -.. warning:: Earlier iterations of this documentation +.. warning:: + + Earlier iterations of this documentation (pre-version-1.3) encouraged the application developer to use ZPT-specific APIs such as :func:`pyramid.chameleon_zpt.render_template_to_response` and diff --git a/docs/narr/urldispatch.rst b/docs/narr/urldispatch.rst index a6e46515f..9d5229c70 100644 --- a/docs/narr/urldispatch.rst +++ b/docs/narr/urldispatch.rst @@ -353,7 +353,9 @@ process. Examples of route predicate arguments are ``pattern``, ``xhr``, and Other arguments are ``name`` and ``factory``. These arguments represent neither predicates nor view configuration information. -.. warning:: Some arguments are view-configuration related arguments, such as +.. warning:: + + Some arguments are view-configuration related arguments, such as ``view_renderer``. These only have an effect when the route configuration names a ``view`` and these arguments have been deprecated as of :app:`Pyramid` 1.1. @@ -646,7 +648,9 @@ other non-``name`` and non-``pattern`` arguments to exception to this rule is use of the ``pregenerator`` argument, which is not ignored when ``static`` is ``True``. -.. note:: the ``static`` argument to +.. note:: + + the ``static`` argument to :meth:`~pyramid.config.Configurator.add_route` is new as of :app:`Pyramid` 1.1. @@ -1098,7 +1102,9 @@ permission. Obviously you can do more generic things than inspect the routes match dict to see if the ``article`` argument matches a particular string; our sample ``Article`` factory class is not very ambitious. -.. note:: See :ref:`security_chapter` for more information about +.. note:: + + See :ref:`security_chapter` for more information about :app:`Pyramid` security and ACLs. .. index:: -- cgit v1.2.3