Skip to content

Commit

Permalink
clean up ".. warning" and ".. note" broken by docutils 0.8 upgrade
Browse files Browse the repository at this point in the history 
ignore _themes/README.rst during docs compilation
  • Loading branch information
Michael authored and michr committed Sep 29, 2011
1 parent ee95e49 commit f361e49
Show file tree
Hide file tree
Showing 23 changed files with 372 additions and 319 deletions.
8 changes: 6 additions & 2 deletions docs/conf.py
View file
Original file line number Original file line Diff line number Diff line change
Expand Up @@ -106,6 +106,10 @@ def nothing(*arg):
# List of documents that shouldn't be included in the build. # List of documents that shouldn't be included in the build.
#unused_docs = [] #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 # List of directories, relative to source directories, that shouldn't be searched
# for source files. # for source files.
#exclude_dirs = [] #exclude_dirs = []
Expand Down Expand Up @@ -381,7 +385,7 @@ def frontmatter(name, arguments, options, content, lineno,
% reset page counter % reset page counter
\setcounter{page}{1} \setcounter{page}{1}
% suppress first toc pagenum % suppress first toc pagenum
\addtocontents{toc}{\protect\thispagestyle{empty}} \addtocontents{toc}{\protect\thispagestyle{empty}}
""", """,
format='latex')] format='latex')]


Expand All @@ -394,7 +398,7 @@ def mainmatter(name, arguments, options, content, lineno,
% allow part/chapter/section numbering % allow part/chapter/section numbering
\setcounter{secnumdepth}{2} \setcounter{secnumdepth}{2}
% get headers back % get headers back
\pagestyle{fancy} \pagestyle{fancy}
\fancyhf{} \fancyhf{}
\renewcommand{\headrulewidth}{0.5pt} \renewcommand{\headrulewidth}{0.5pt}
\renewcommand{\footrulewidth}{0pt} \renewcommand{\footrulewidth}{0pt}
Expand Down
28 changes: 14 additions & 14 deletions docs/designdefense.rst
View file
Original file line number Original file line Diff line number Diff line change
Expand Up @@ -245,14 +245,14 @@ 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 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. registry within :app:`Pyramid` because it ultimately proved a better fit.


.. note:: We continued using ZCA registry rather than disusing it in .. note::
favor of using the registry implementation in
:mod:`repoze.component` largely because the ZCA concept of We continued using ZCA registry rather than disusing it in favor of using the
interfaces provides for use of an interface hierarchy, which is registry implementation in :mod:`repoze.component` largely because the ZCA
useful in a lot of scenarios (such as context type inheritance). concept of interfaces provides for use of an interface hierarchy, which is
Coming up with a marker type that was something like an interface useful in a lot of scenarios (such as context type inheritance). Coming up
that allowed for this functionality seemed like it was just with a marker type that was something like an interface that allowed for this
reinventing the wheel. functionality seemed like it was just reinventing the wheel.


Making framework developers and extenders understand the ZCA registry API is Making framework developers and extenders understand the ZCA registry API is
a trade-off. We (the :app:`Pyramid` developers) like the features that the a trade-off. We (the :app:`Pyramid` developers) like the features that the
Expand Down Expand Up @@ -406,7 +406,7 @@ predicate that narrows matching to something that accepts a JSON response:
:linenos: :linenos:
from pyramid.view import view_config 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') accept='application/json', renderer='json')
def post_view(request): def post_view(request):
return 'POSTed' return 'POSTed'
Expand Down Expand Up @@ -791,12 +791,12 @@ very well in general. Quoting from the `Model-View-Controller Wikipedia entry
often via a registered handler or callback and converts the event often via a registered handler or callback and converts the event
into appropriate user action, understandable for the model. 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 resulting in a change in the model's state. (For example, the
controller updates the user's shopping cart.)[5] controller updates the user's shopping cart.)[5]
A view queries the model in order to generate an appropriate 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. contents). Note that the view gets its own data from the model.
The controller may (in some implementations) issue a general The controller may (in some implementations) issue a general
Expand Down Expand Up @@ -1101,7 +1101,7 @@ printed, right? Sadly, no:


.. code-block:: text .. code-block:: text
[chrism@thinko]$ python app.py [chrism@thinko]$ python app.py
[<function foo at 0x7f4ea41ab1b8>, [<function foo at 0x7f4ea41ab1b8>,
<function foo at 0x7f4ea41ab230>, <function foo at 0x7f4ea41ab230>,
<function bar at 0x7f4ea41ab2a8>] <function bar at 0x7f4ea41ab2a8>]
Expand Down Expand Up @@ -1402,7 +1402,7 @@ global*:
else: else:
error = 'Invalid username/password' error = 'Invalid username/password'
# this is executed if the request method was GET or the # 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 The `Pylons 1.X <http://pylonsproject.org>`_ web framework uses a similar
strategy. It calls these things "Stacked Object Proxies", so, for purposes strategy. It calls these things "Stacked Object Proxies", so, for purposes
Expand Down Expand Up @@ -1502,7 +1502,7 @@ comments take into account what we've discussed in the
def hello_world(request): # accepts a request; no request thread local reqd def hello_world(request): # accepts a request; no request thread local reqd
# explicit response object means no response threadlocal # explicit response object means no response threadlocal
return Response('Hello world!') return Response('Hello world!')
if __name__ == '__main__': if __name__ == '__main__':
from pyramid.config import Configurator from pyramid.config import Configurator
Expand Down
20 changes: 12 additions & 8 deletions docs/narr/assets.rst
View file
Original file line number Original file line Diff line number Diff line change
Expand Up @@ -98,10 +98,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 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. the application root URL, e.g. ``/static`` or as an external URL.


.. note:: :meth:`~pyramid.config.Configurator.add_static_view` cannot serve a .. note::
single file, nor can it serve a directory of static files directly
relative to the root URL of a :app:`Pyramid` application. For these :meth:`~pyramid.config.Configurator.add_static_view` cannot serve a single
features, see :ref:`advanced_static`. 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 Here's an example of a use of
:meth:`~pyramid.config.Configurator.add_static_view` that will serve files up :meth:`~pyramid.config.Configurator.add_static_view` that will serve files up
Expand Down Expand Up @@ -170,7 +172,7 @@ be fed a ``name`` argument which is ``http://example.com/images``:
:linenos: :linenos:
# config is an instance of pyramid.config.Configurator # 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') path='mypackage:images')
Because :meth:`~pyramid.config.Configurator.add_static_view` is provided with Because :meth:`~pyramid.config.Configurator.add_static_view` is provided with
Expand Down Expand Up @@ -250,7 +252,7 @@ the the ``path`` given may be ``mypackage:images``:
.. code-block:: python .. code-block:: python
:linenos: :linenos:
config.add_static_view(name='http://example.com/images', config.add_static_view(name='http://example.com/images',
path='mypackage:images') path='mypackage:images')
Under such a configuration, the URL generated by ``static_url`` for Under such a configuration, the URL generated by ``static_url`` for
Expand Down Expand Up @@ -305,7 +307,9 @@ instance of this class is actually used by the
:meth:`~pyramid.config.Configurator.add_static_view` configuration method, so :meth:`~pyramid.config.Configurator.add_static_view` configuration method, so
its behavior is almost exactly the same once it's configured. 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` :term:`traversal`, it will only work if you use :term:`URL dispatch`
exclusively. The root-relative route we'll be registering will always be exclusively. The root-relative route we'll be registering will always be
matched before traversal takes place, subverting any views registered via matched before traversal takes place, subverting any views registered via
Expand Down Expand Up @@ -384,7 +388,7 @@ Or you might register it to be the view callable for a particular route:
.. code-block:: python .. code-block:: python
:linenos: :linenos:
config.add_route('favicon', '/favicon.ico', config.add_route('favicon', '/favicon.ico',
view='myapp.views.favicon_view') view='myapp.views.favicon_view')
Because this is a simple view callable, it can be protected with a Because this is a simple view callable, it can be protected with a
Expand Down
12 changes: 7 additions & 5 deletions docs/narr/firstapp.rst
View file
Original file line number Original file line Diff line number Diff line change
Expand Up @@ -120,11 +120,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 passed to the ``Response`` constructor as the *body* of the response. In the
``goodbye_world`` function, the string ``'Goodbye world!'`` is passed. ``goodbye_world`` function, the string ``'Goodbye world!'`` is passed.


.. note:: As we'll see in later chapters, returning a literal .. note::
: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 As we'll see in later chapters, returning a literal :term:`response` object
a renderer, our view callable is allowed to return a value that the from a view callable is not always required; we can instead use a
renderer understands, and the renderer generates a response on our behalf. :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:: .. index::
single: imperative configuration single: imperative configuration
Expand Down
54 changes: 29 additions & 25 deletions docs/narr/hooks.rst
View file
Original file line number Original file line Diff line number Diff line change
Expand Up @@ -55,18 +55,21 @@ Here's some sample code that implements a minimal NotFound view callable:
def notfound_view(request): def notfound_view(request):
return HTTPNotFound() return HTTPNotFound()
.. note:: When a NotFound view callable is invoked, it is passed a .. note::
:term:`request`. The ``exception`` attribute of the request will
be an instance of the :exc:`~pyramid.exceptions.NotFound` When a NotFound view callable is invoked, it is passed a :term:`request`.
exception that caused the not found view to be called. The value The ``exception`` attribute of the request will be an instance of the
of ``request.exception.args[0]`` will be a value explaining why the :exc:`~pyramid.exceptions.NotFound` exception that caused the not found view
not found error was raised. This message will be different when to be called. The value of ``request.exception.args[0]`` will be a value
the ``debug_notfound`` environment setting is true than it is when explaining why the not found error was raised. This message will be
it is false. 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`` .. warning::
passed as the first argument to the view callable will be the
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.exceptions.NotFound` exception instance. If available, the :exc:`~pyramid.exceptions.NotFound` exception instance. If available, the
resource context will still be available as ``request.context``. resource context will still be available as ``request.context``.


Expand Down Expand Up @@ -120,14 +123,15 @@ Here's some sample code that implements a minimal forbidden view:
def forbidden_view(request): def forbidden_view(request):
return Response('forbidden') return Response('forbidden')
.. note:: When a forbidden view callable is invoked, it is passed a .. note::
:term:`request`. The ``exception`` attribute of the request will
be an instance of the :exc:`~pyramid.exceptions.Forbidden` When a forbidden view callable is invoked, it is passed a :term:`request`.
exception that caused the forbidden view to be called. The value The ``exception`` attribute of the request will be an instance of the
of ``request.exception.args[0]`` will be a value explaining why the :exc:`~pyramid.exceptions.Forbidden` exception that caused the forbidden view
forbidden was raised. This message will be different when the to be called. The value of ``request.exception.args[0]`` will be a value
``debug_authorization`` environment setting is true than it is when explaining why the forbidden was raised. This message will be different when
it is false. the ``debug_authorization`` environment setting is true than it is when it is
false.


.. index:: .. index::
single: request factory single: request factory
Expand Down Expand Up @@ -484,7 +488,7 @@ resource by adding a registerAdapter call for
from myapp.traversal import URLGenerator from myapp.traversal import URLGenerator
from myapp.resources import MyRoot from myapp.resources import MyRoot
config.registry.registerAdapter(URLGenerator, (MyRoot, Interface), config.registry.registerAdapter(URLGenerator, (MyRoot, Interface),
IContextURL) IContextURL)
In the above example, the ``myapp.traversal.URLGenerator`` class will be used In the above example, the ``myapp.traversal.URLGenerator`` class will be used
Expand Down Expand Up @@ -647,9 +651,9 @@ follows:
import venusian import venusian
from pyramid.threadlocal import get_current_registry from pyramid.threadlocal import get_current_registry
from mypackage.interfaces import IMyUtility from mypackage.interfaces import IMyUtility
class registerFunction(object): class registerFunction(object):
def __init__(self, path): def __init__(self, path):
self.path = path self.path = path
Expand All @@ -658,11 +662,11 @@ follows:
registry.getUtility(IMyUtility).register( registry.getUtility(IMyUtility).register(
self.path, wrapped self.path, wrapped
) )
def __call__(self, wrapped): def __call__(self, wrapped):
venusian.attach(wrapped, self.register) venusian.attach(wrapped, self.register)
return wrapped return wrapped
This decorator could then be used to register functions throughout This decorator could then be used to register functions throughout
your code: your code:


Expand Down
17 changes: 9 additions & 8 deletions docs/narr/i18n.rst
View file
Original file line number Original file line Diff line number Diff line change
Expand Up @@ -95,7 +95,7 @@ translations of the same msgid, in case they conflict.
:linenos: :linenos:
from pyramid.i18n import TranslationString from pyramid.i18n import TranslationString
ts = TranslationString('Add ${number}', mapping={'number':1}, ts = TranslationString('Add ${number}', mapping={'number':1},
domain='form') domain='form')
The above translation string named a domain of ``form``. A The above translation string named a domain of ``form``. A
Expand Down Expand Up @@ -170,7 +170,7 @@ to:
:linenos: :linenos:
from pyramid.i18n import TranslationString as _ from pyramid.i18n import TranslationString as _
ts = _('Add ${number}', msgid='add-number', mapping={'number':1}, ts = _('Add ${number}', msgid='add-number', mapping={'number':1},
domain='pyramid') domain='pyramid')
You can set up your own translation string factory much like the one You can set up your own translation string factory much like the one
Expand Down Expand Up @@ -527,7 +527,7 @@ translation in a view component of an application might look like so:
from pyramid.i18n import get_localizer from pyramid.i18n import get_localizer
from pyramid.i18n import TranslationString from pyramid.i18n import TranslationString
ts = TranslationString('Add ${number}', mapping={'number':1}, ts = TranslationString('Add ${number}', mapping={'number':1},
domain='pyramid') domain='pyramid')
def aview(request): def aview(request):
Expand All @@ -542,9 +542,10 @@ represented by the request. The translation returned from its
``domain`` attribute of the provided translation string as well as the ``domain`` attribute of the provided translation string as well as the
locale of the localizer. locale of the localizer.


.. note:: If you're using :term:`Chameleon` templates, you don't need .. note::
to pre-translate translation strings this way. See
:ref:`chameleon_translation_strings`. If you're using :term:`Chameleon` templates, you don't need to pre-translate
translation strings this way. See :ref:`chameleon_translation_strings`.


.. index:: .. index::
single: pluralizing (i18n) single: pluralizing (i18n)
Expand Down Expand Up @@ -836,7 +837,7 @@ Then as a part of the code of a custom :term:`locale negotiator`:


.. code-block:: python .. code-block:: python
:linenos: :linenos:
from pyramid.threadlocal import get_current_registry from pyramid.threadlocal import get_current_registry
settings = get_current_registry().settings settings = get_current_registry().settings
languages = settings['available_languages'].split() languages = settings['available_languages'].split()
Expand Down Expand Up @@ -889,7 +890,7 @@ application startup. For example:
:linenos: :linenos:
from pyramid.config import Configurator from pyramid.config import Configurator
config.add_translation_dirs('my.application:locale/', config.add_translation_dirs('my.application:locale/',
'another.application:locale/') 'another.application:locale/')
A message catalog in a translation directory added via A message catalog in a translation directory added via
Expand Down
21 changes: 11 additions & 10 deletions docs/narr/install.rst
View file
Original file line number Original file line Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ Before You Install
------------------ ------------------


You will need `Python <http://python.org>`_ version 2.4 or better to You will need `Python <http://python.org>`_ version 2.4 or better to
run :app:`Pyramid`. run :app:`Pyramid`.


.. sidebar:: Python Versions .. sidebar:: Python Versions


Expand Down Expand Up @@ -143,7 +143,7 @@ setuptools`` within the Python interpreter you'd like to run
.. code-block:: text .. code-block:: text
[chrism@vitaminf pyramid]$ python [chrism@vitaminf pyramid]$ python
Python 2.4.5 (#1, Aug 29 2008, 12:27:37) Python 2.4.5 (#1, Aug 29 2008, 12:27:37)
[GCC 4.0.1 (Apple Inc. build 5465)] on darwin [GCC 4.0.1 (Apple Inc. build 5465)] on darwin
Type "help", "copyright", "credits" or "license" for more information. Type "help", "copyright", "credits" or "license" for more information.
>>> import setuptools >>> import setuptools
Expand Down Expand Up @@ -221,14 +221,15 @@ following:
New python executable in env/bin/python New python executable in env/bin/python
Installing setuptools.............done. Installing setuptools.............done.
.. warning:: Using ``--no-site-packages`` when generating your .. warning::
virtualenv is *very important*. This flag provides the necessary
isolation for running the set of packages required by Using ``--no-site-packages`` when generating your virtualenv is *very
:app:`Pyramid`. If you do not specify ``--no-site-packages``, important*. This flag provides the necessary isolation for running the set of
it's possible that :app:`Pyramid` will not install properly into packages required by :app:`Pyramid`. If you do not specify
the virtualenv, or, even if it does, may not run properly, ``--no-site-packages``, it's possible that :app:`Pyramid` will not install
depending on the packages you've already got installed into your properly into the virtualenv, or, even if it does, may not run properly,
Python's "main" site-packages dir. 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 .. warning:: If you're on UNIX, *do not* use ``sudo`` to run the
``virtualenv`` script. It's perfectly acceptable (and desirable) ``virtualenv`` script. It's perfectly acceptable (and desirable)
Expand Down
10 changes: 6 additions & 4 deletions docs/narr/muchadoabouttraversal.rst
View file
Original file line number Original file line Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ Traversal is an alternative to :term:`URL dispatch` which allows
:app:`Pyramid` applications to map URLs to code. :app:`Pyramid` applications to map URLs to code.


.. note:: .. note::

Ex-Zope users whom are already familiar with traversal and view lookup Ex-Zope users whom are already familiar with traversal and view lookup
conceptually may want to skip directly to the :ref:`traversal_chapter` conceptually may want to skip directly to the :ref:`traversal_chapter`
chapter, which discusses technical details. This chapter is mostly aimed chapter, which discusses technical details. This chapter is mostly aimed
Expand Down Expand Up @@ -161,7 +161,7 @@ interpreter prompt if you don't believe us:
.. code-block:: text .. code-block:: text
:linenos: :linenos:
Python 2.4.6 (#2, Apr 29 2010, 00:31:48) Python 2.4.6 (#2, Apr 29 2010, 00:31:48)
[GCC 4.4.3] on linux2 [GCC 4.4.3] on linux2
Type "help", "copyright", "credits" or "license" for more information. Type "help", "copyright", "credits" or "license" for more information.
>>> adict = {} >>> adict = {}
Expand Down Expand Up @@ -304,6 +304,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 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. 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::
:term:`URL dispatch` in the same :app:`Pyramid` application. See the
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. :ref:`hybrid_chapter` chapter for details.
Loading

0 comments on commit f361e49

Please sign in to comment.