Permalink
Browse files

fix up all the ..note and ..warning sphinx errors

excluded _themes/README.rst from being looked ed
  • Loading branch information...
1 parent ee885af commit 5f7559edd018872989ae6ae69b0d3a081a912700 Michael committed Sep 28, 2011
View
@@ -106,6 +106,10 @@ def nothing(*arg):
# List of documents that shouldn't be included in the build.
#unused_docs = []
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+exclude_patterns = ['_themes/README.rst',]
+
# List of directories, relative to source directories, that shouldn't be searched
# for source files.
#exclude_dirs = []
View
@@ -245,7 +245,9 @@ its API is much nicer than the ZCA registry API, work on it was largely
abandoned and it is not used in :app:`Pyramid`. We continued to use a ZCA
registry within :app:`Pyramid` because it ultimately proved a better fit.
-.. note:: We continued using ZCA registry rather than disusing it in
+.. note::
+
+ We continued using ZCA registry rather than disusing it in
favor of using the registry implementation in
:mod:`repoze.component` largely because the ZCA concept of
interfaces provides for use of an interface hierarchy, which is
@@ -406,7 +408,7 @@ predicate that narrows matching to something that accepts a JSON response:
:linenos:
from pyramid.view import view_config
- @view_config(name='post_view', request_method='POST',
+ @view_config(name='post_view', request_method='POST',
accept='application/json', renderer='json')
def post_view(request):
return 'POSTed'
@@ -791,12 +793,12 @@ very well in general. Quoting from the `Model-View-Controller Wikipedia entry
often via a registered handler or callback and converts the event
into appropriate user action, understandable for the model.
- The controller notifies the model of the user action, possibly
+ The controller notifies the model of the user action, possibly
resulting in a change in the model's state. (For example, the
controller updates the user's shopping cart.)[5]
A view queries the model in order to generate an appropriate
- user interface (for example, the view lists the shopping cart's
+ user interface (for example, the view lists the shopping cart's
contents). Note that the view gets its own data from the model.
The controller may (in some implementations) issue a general
@@ -1206,7 +1208,7 @@ printed, right? Sadly, no:
.. code-block:: text
- [chrism@thinko]$ python app.py
+ [chrism@thinko]$ python app.py
[<function foo at 0x7f4ea41ab1b8>,
<function foo at 0x7f4ea41ab230>,
<function bar at 0x7f4ea41ab2a8>]
@@ -1539,7 +1541,7 @@ global*:
else:
error = 'Invalid username/password'
# this is executed if the request method was GET or the
- # credentials were invalid
+ # credentials were invalid
The `Pylons 1.X <http://pylonsproject.org>`_ web framework uses a similar
strategy. It calls these things "Stacked Object Proxies", so, for purposes
@@ -1639,7 +1641,7 @@ comments take into account what we've discussed in the
def hello_world(request): # accepts a request; no request thread local reqd
# explicit response object means no response threadlocal
- return Response('Hello world!')
+ return Response('Hello world!')
if __name__ == '__main__':
from pyramid.config import Configurator
@@ -1658,48 +1660,48 @@ be done from within other includes. Any directive can be used within an
include that can be used outside of one (such as
:meth:`~pyramid.config.Configurator.add_view`, etc).
-Pyramid has a conflict detection system that will throw an error if two
-included externals try to add "the same" configuration in a conflicting
-way (such as both externals trying to add a route using the same name,
-or both externals trying to add a view with the same set of predicates).
-It's awful tempting to call this set of features something that can be
-used to compose a system out of "pluggable applications". But in
-reality, there are a number of problems with claiming this:
-
-- The terminology is strained. Pyramid really has no notion of a
- plurality of "applications", just a way to compose configuration
- from multiple sources to create a single WSGI application. That
- WSGI application may gain behavior by including or disincluding
- configuration, but once it's all composed together, Pyramid
- doesn't really provide any machinery which can be used to demarcate
- the boundaries of one "application" (in the sense of configuration
- from an external that adds routes, views, etc) from another.
-
-- Pyramid doesn't provide enough "rails" to make it possible to
- integrate truly honest-to-god, download-an-app-from-a-random-place
- and-plug-it-in-to-create-a-system "pluggable" applications.
- Because Pyramid itself isn't opinionated (it doesn't mandate a
- particular kind of database, it offers multiple ways to map URLs
- to code, etc), it's unlikely that someone who creates something
- "application-like" will be able to casually redistribute it
- to J. Random Pyramid User and have it "just work" by asking him
- to config.include a function from the package.
- This is particularly true of very high level components such
- as blogs, wikis, twitter clones, commenting systems, etc.
- The "integrator" (the Pyramid developer who has downloaded a
- package advertised as a "pluggable app") will almost certainly
- have made different choices about e.g. what type of persistence
- system he's using, and for the integrator to appease the
- requirements of the "pluggable application", he may be required
- to set up a different database, make changes to his own code
- to prevent his application from "shadowing" the pluggable
- app (or vice versa), and any other number of arbitrary
- changes.
-
-For this reason, we claim that Pyramid has "extensible" applications,
-not pluggable applications. Any Pyramid application can be extended
-without forking it as long as its configuration statements have been
-composed into things that can be pulled in via "config.include".
+Pyramid has a conflict detection system that will throw an error if two
+included externals try to add "the same" configuration in a conflicting
+way (such as both externals trying to add a route using the same name,
+or both externals trying to add a view with the same set of predicates).
+It's awful tempting to call this set of features something that can be
+used to compose a system out of "pluggable applications". But in
+reality, there are a number of problems with claiming this:
+
+- The terminology is strained. Pyramid really has no notion of a
+ plurality of "applications", just a way to compose configuration
+ from multiple sources to create a single WSGI application. That
+ WSGI application may gain behavior by including or disincluding
+ configuration, but once it's all composed together, Pyramid
+ doesn't really provide any machinery which can be used to demarcate
+ the boundaries of one "application" (in the sense of configuration
+ from an external that adds routes, views, etc) from another.
+
+- Pyramid doesn't provide enough "rails" to make it possible to
+ integrate truly honest-to-god, download-an-app-from-a-random-place
+ and-plug-it-in-to-create-a-system "pluggable" applications.
+ Because Pyramid itself isn't opinionated (it doesn't mandate a
+ particular kind of database, it offers multiple ways to map URLs
+ to code, etc), it's unlikely that someone who creates something
+ "application-like" will be able to casually redistribute it
+ to J. Random Pyramid User and have it "just work" by asking him
+ to config.include a function from the package.
+ This is particularly true of very high level components such
+ as blogs, wikis, twitter clones, commenting systems, etc.
+ The "integrator" (the Pyramid developer who has downloaded a
+ package advertised as a "pluggable app") will almost certainly
+ have made different choices about e.g. what type of persistence
+ system he's using, and for the integrator to appease the
+ requirements of the "pluggable application", he may be required
+ to set up a different database, make changes to his own code
+ to prevent his application from "shadowing" the pluggable
+ app (or vice versa), and any other number of arbitrary
+ changes.
+
+For this reason, we claim that Pyramid has "extensible" applications,
+not pluggable applications. Any Pyramid application can be extended
+without forking it as long as its configuration statements have been
+composed into things that can be pulled in via "config.include".
It's also perfectly reasonable for a single developer or team to create a set
of interoperating components which can be enabled or disabled by using
View
@@ -102,10 +102,12 @@ 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
- 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`.
+.. 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`.
Here's an example of a use of
:meth:`~pyramid.config.Configurator.add_static_view` that will serve files up
@@ -174,7 +176,7 @@ be fed a ``name`` argument which is ``http://example.com/images``:
:linenos:
# config is an instance of pyramid.config.Configurator
- config.add_static_view(name='http://example.com/images',
+ config.add_static_view(name='http://example.com/images',
path='mypackage:images')
Because :meth:`~pyramid.config.Configurator.add_static_view` is provided with
@@ -255,7 +257,7 @@ the the ``path`` given may be ``mypackage:images``:
.. code-block:: python
:linenos:
- config.add_static_view(name='http://example.com/images',
+ config.add_static_view(name='http://example.com/images',
path='mypackage:images')
Under such a configuration, the URL generated by ``static_url`` for
@@ -310,14 +312,15 @@ 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
``add_view`` (at least those without a ``route_name``). A
- :class:`~pyramid.static.static_view` static view cannot be made
- root-relative when you use traversal unless it's registered as a
- :term:`Not Found view`.
+ :class:`~pyramid.static.static_view` static view cannot be made root-relative
+ when you use traversal unless it's registered as a :term:`Not Found view`.
To serve files within a directory located on your filesystem at
``/path/to/static/dir`` as the result of a "catchall" route hanging from the
@@ -122,11 +122,13 @@ class. In the ``hello_world`` function, the string ``'Hello world!'`` is
passed to the ``Response`` constructor as the *body* of the response. In the
``goodbye_world`` function, the string ``'Goodbye world!'`` is passed.
-.. note:: As we'll see in later chapters, returning a literal
- :term:`response` object from a view callable is not always required; we
- can instead use a :term:`renderer` in our view configurations. If we use
- a renderer, our view callable is allowed to return a value that the
- renderer understands, and the renderer generates a response on our behalf.
+.. note::
+
+ As we'll see in later chapters, returning a literal :term:`response` object
+ from a view callable is not always required; we can instead use a
+ :term:`renderer` in our view configurations. If we use a renderer, our view
+ callable is allowed to return a value that the renderer understands, and the
+ renderer generates a response on our behalf.
.. index::
single: imperative configuration
View
@@ -55,18 +55,21 @@ 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
- :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
- ``request.exception.message`` will be a value explaining why the not found
- error was raised. This message will be different when the
- ``debug_notfound`` environment setting is true than it is when it is
- false.
-
-.. 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
+.. 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 ``request.exception.message`` will be
+ a value explaining why the not found error was raised. This message will be
+ different when the ``debug_notfound`` environment setting is true than it is
+ when it is false.
+
+.. 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
available, the resource context will still be available as
``request.context``.
@@ -121,15 +124,16 @@ 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
- :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
- ``request.exception.message`` will be a value explaining why the forbidden
- was raised and ``request.exception.result`` will be extended information
- about the forbidden exception. These messages will be different when the
- ``debug_authorization`` environment setting is true than it is when it is
- false.
+.. 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 ``request.exception.message`` will
+ be a value explaining why the forbidden was raised and
+ ``request.exception.result`` will be extended information about the forbidden
+ exception. These messages will be different when the ``debug_authorization``
+ environment setting is true than it is when it is false.
.. index::
single: request factory
@@ -606,7 +610,7 @@ marked up with ``zope.interface.implements(IResponse)``:
class MyResponse(object):
implements(IResponse)
- # ... an implementation of every method and attribute
+ # ... an implementation of every method and attribute
# documented in IResponse should follow ...
When an alternate response object implementation is returned by a view
View
@@ -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`.
View
@@ -10,7 +10,7 @@ Before You Install
------------------
You will need `Python <http://python.org>`_ version 2.5 or better to
-run :app:`Pyramid`.
+run :app:`Pyramid`.
.. sidebar:: Python Versions
@@ -150,7 +150,7 @@ setuptools`` within the Python interpreter you'd like to run
.. code-block:: text
[chrism@vitaminf pyramid]$ python
- Python 2.6.5 (r265:79063, Apr 29 2010, 00:31:32)
+ Python 2.6.5 (r265:79063, Apr 29 2010, 00:31:32)
[GCC 4.4.3] on linux2
Type "help", "copyright", "credits" or "license" for more information.
>>> import setuptools
@@ -229,14 +229,15 @@ following:
New python executable in env/bin/python
Installing setuptools.............done.
-.. 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``,
- it's possible that :app:`Pyramid` will not install properly into
- the virtualenv, or, even if it does, may not run properly,
- depending on the packages you've already got installed into your
- Python's "main" site-packages dir.
+.. 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``, it's possible that :app:`Pyramid` will not install
+ properly into the virtualenv, or, even if it does, may not run properly,
+ depending on the packages you've already got installed into your Python's
+ "main" site-packages dir.
.. warning:: If you're on UNIX, *do not* use ``sudo`` to run the
``virtualenv`` script. It's perfectly acceptable (and desirable)
@@ -350,5 +351,5 @@ various Chameleon libraries, WebOb, Paste, PasteScript, and
PasteDeploy libraries are installed.
Additionally, as chronicled in :ref:`project_narr`, scaffolds will be registered,
-which make it easy to start a new :app:`Pyramid` project.
+which make it easy to start a new :app:`Pyramid` project.
Oops, something went wrong.

0 comments on commit 5f7559e

Please sign in to comment.