From 5d22ee06e7cc35e3552365b5d9ff78f3f281d714 Mon Sep 17 00:00:00 2001 From: Blaise Laflamme Date: Sat, 27 Nov 2010 23:31:36 -0500 Subject: Docs gardening --- docs/narr/project.rst | 21 +++++++++++++++------ 1 file changed, 15 insertions(+), 6 deletions(-) (limited to 'docs/narr') diff --git a/docs/narr/project.rst b/docs/narr/project.rst index 8901c1a4e..944368cba 100644 --- a/docs/narr/project.rst +++ b/docs/narr/project.rst @@ -257,7 +257,7 @@ points to *your application* as opposed to any other section within the ``.ini`` file. For example, if your application ``.ini`` file might have a ``[app:MyProject]`` section that looks like so: -.. code-block:: ini +.. code-block:: guess :linenos: [app:MyProject] @@ -271,7 +271,7 @@ points to *your application* as opposed to any other section within the If so, you can use the following command to invoke a debug shell using the name ``MyProject`` as a section name: -.. code-block:: text +.. code-block:: text [chrism@vitaminf shellenv]$ ../bin/paster pshell development.ini MyProject Python 2.4.5 (#1, Aug 29 2008, 12:27:37) @@ -288,7 +288,7 @@ happen, even if you have IPython installed, you can pass the ``--disable-ipython`` flag to the ``pshell`` command to use a standard Python interpreter shell unconditionally. -.. code-block:: text +.. code-block:: text [chrism@vitaminf shellenv]$ ../bin/paster pshell --disable-ipython \ development.ini MyProject @@ -303,7 +303,7 @@ Python interpreter shell unconditionally. than an ``app``. For example, if you have the following ``.ini`` file content: - .. code-block:: ini + .. code-block:: guess :linenos: [app:MyProject] @@ -432,7 +432,9 @@ name except for case). All :app:`Pyramid` ``paster`` -generated projects share a similar structure. The ``MyProject`` project we've generated has the following directory -structure:: +structure: + +.. code-block:: text MyProject/ |-- CHANGES.txt @@ -493,6 +495,7 @@ serve``, as well as the deployment settings provided to that application. The generated ``development.ini`` file looks like so: .. literalinclude:: MyProject/development.ini + :language: python :linenos: This file contains several "sections" including ``[app:MyProject]``, @@ -618,6 +621,7 @@ distributing your application. Our generated ``setup.py`` looks like this: .. literalinclude:: MyProject/setup.py + :language: python :linenos: The ``setup.py`` file calls the setuptools ``setup`` function, which @@ -655,7 +659,7 @@ file when distributing your application to other people, or when versioning your application for your own use. For fun, you can try this command now: -.. code-block:: python +.. code-block:: text $ python setup.py sdist @@ -686,6 +690,7 @@ contains various settings related to testing and internationalization: Our generated ``setup.cfg`` looks like this: .. literalinclude:: MyProject/setup.cfg + :language: guess :linenos: The values in the default setup file allow various commonly-used @@ -733,6 +738,7 @@ This is the file named ``__init__.py``. The presence of an ``__init__.py`` also informs Python that the directory which contains it is a *package*. .. literalinclude:: MyProject/myproject/__init__.py + :language: python :linenos: #. Line 1 imports the :term:`Configurator` class from @@ -779,6 +785,7 @@ code which accepts a :term:`request` and which returns a :term:`response`. .. literalinclude:: MyProject/myproject/views.py + :language: python :linenos: This bit of code was registered as the view callable within ``__init__.py`` @@ -825,6 +832,7 @@ and provide APIs which mutate and return this data. We write a class named ``MyModel`` that provides the behavior. .. literalinclude:: MyProject/myproject/models.py + :language: python :linenos: #. Lines 1-2 define the MyModel class. @@ -871,6 +879,7 @@ by view functions themselves. See :ref:`templates_used_directly` and The ``tests.py`` module includes unit tests for your application. .. literalinclude:: MyProject/myproject/tests.py + :language: python :linenos: This sample ``tests.py`` file has a single unit test defined within -- cgit v1.2.3 From 8069e93ea3d1d8a837ad427023f9f245fa3204e3 Mon Sep 17 00:00:00 2001 From: Blaise Laflamme Date: Sat, 27 Nov 2010 23:37:04 -0500 Subject: Fixed wrong type for code rendering --- docs/narr/project.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/narr') diff --git a/docs/narr/project.rst b/docs/narr/project.rst index 944368cba..97db534cb 100644 --- a/docs/narr/project.rst +++ b/docs/narr/project.rst @@ -495,7 +495,7 @@ serve``, as well as the deployment settings provided to that application. The generated ``development.ini`` file looks like so: .. literalinclude:: MyProject/development.ini - :language: python + :language: guess :linenos: This file contains several "sections" including ``[app:MyProject]``, -- cgit v1.2.3 From 42e220dfa80e3d1a065e7d3e8ccf4b8fd3039e63 Mon Sep 17 00:00:00 2001 From: Blaise Laflamme Date: Sat, 27 Nov 2010 23:44:59 -0500 Subject: Reformatted ini file like the --- docs/narr/project.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) (limited to 'docs/narr') diff --git a/docs/narr/project.rst b/docs/narr/project.rst index 97db534cb..1758e9d00 100644 --- a/docs/narr/project.rst +++ b/docs/narr/project.rst @@ -315,8 +315,9 @@ Python interpreter shell unconditionally. default_locale_name = en [pipeline:main] - pipeline = egg:WebError#evalerror - MyProject + pipeline = + egg:WebError#evalerror + MyProject Use ``MyProject`` instead of ``main`` as the section name argument to ``pshell`` against the above ``.ini`` file (e.g. ``paster pshell -- cgit v1.2.3 From 23bfce0ea0fae605f67547f7b12e91fbe329d506 Mon Sep 17 00:00:00 2001 From: Blaise Laflamme Date: Sun, 28 Nov 2010 02:21:38 -0500 Subject: Narrative doc cleanup --- docs/narr/MyProject/setup.cfg | 10 +-- docs/narr/declarative.rst | 178 ++++++++++++++++++++++-------------------- docs/narr/environment.rst | 4 +- docs/narr/extending.rst | 7 +- docs/narr/firstapp.rst | 2 +- docs/narr/hooks.rst | 12 +-- docs/narr/i18n.rst | 37 ++++++--- docs/narr/resources.rst | 2 +- docs/narr/security.rst | 8 +- docs/narr/startup.rst | 2 + docs/narr/templates.rst | 30 +++++-- docs/narr/traversal.rst | 8 +- docs/narr/urldispatch.rst | 4 +- docs/narr/vhosting.rst | 3 +- docs/narr/views.rst | 2 +- docs/narr/zca.rst | 1 + 16 files changed, 183 insertions(+), 127 deletions(-) (limited to 'docs/narr') diff --git a/docs/narr/MyProject/setup.cfg b/docs/narr/MyProject/setup.cfg index de38b5616..332e80a60 100644 --- a/docs/narr/MyProject/setup.cfg +++ b/docs/narr/MyProject/setup.cfg @@ -1,9 +1,9 @@ [nosetests] -match=^test -nocapture=1 -cover-package=myproject -with-coverage=1 -cover-erase=1 +match = ^test +nocapture = 1 +cover-package = myproject +with-coverage = 1 +cover-erase = 1 [compile_catalog] directory = myproject/locale diff --git a/docs/narr/declarative.rst b/docs/narr/declarative.rst index b9dbcab7d..3c5eb9db4 100644 --- a/docs/narr/declarative.rst +++ b/docs/narr/declarative.rst @@ -65,8 +65,8 @@ previously created ``helloworld.py``: + view="helloworld.hello_world" + /> @@ -120,8 +120,8 @@ filesystem. Let's take a look at that ``configure.zcml`` file again: + view="helloworld.hello_world" + /> @@ -181,11 +181,11 @@ start. For example, the following ZCML file has two conflicting + /> + /> @@ -241,13 +241,13 @@ the previously created ``helloworld.py``: + view="helloworld.hello_world" + /> + /> @@ -255,7 +255,8 @@ This pair of files forms an application functionally equivalent to the application we created earlier in :ref:`helloworld_imperative`. We can run it the same way. -.. code-block:: bash +.. code-block:: text + :linenos: $ python helloworld.py serving on 0.0.0.0:8080 view at http://127.0.0.1:8080 @@ -308,13 +309,13 @@ which sits next to ``helloworld.py``. Let's take a look at the + view="helloworld.hello_world" + /> + name="goodbye" + view="helloworld.goodbye_world" + /> @@ -352,6 +353,7 @@ The ``configure.zcml`` ZCML file contains this bit of XML within the ```` root tag: .. code-block:: xml + :linenos: @@ -399,12 +401,12 @@ The ``configure.zcml`` ZCML file contains these bits of XML *after* the + /> + /> These ```` declaration tags direct :app:`Pyramid` to create two :term:`view configuration` registrations. The first ```` @@ -451,12 +453,12 @@ completely equivalent: + /> + /> .. topic:: Goodbye Before Hello @@ -466,11 +468,11 @@ completely equivalent: + /> + /> We've now configured a :app:`Pyramid` helloworld application declaratively. More information about this mode of configuration is @@ -556,10 +558,10 @@ example of a view declaration in ZCML is as follows: :linenos: + context=".models.Hello" + view=".views.hello_world" + name="hello.html" + /> The above maps the ``.views.hello_world`` view callable function to the following set of :term:`context finding` results: @@ -589,9 +591,9 @@ type: :linenos: + context=".models.Hello" + view=".views.hello_world" + /> A *default view callable* simply has no ``name`` attribute. For the above registration, when a :term:`context` is found that is of the @@ -607,10 +609,10 @@ string as its ``name`` attribute: :linenos: + context=".models.Hello" + view=".views.hello_world" + name="" + /> You may also declare that a view callable is good for any context type by using the special ``*`` character as the value of the ``context`` @@ -620,10 +622,10 @@ attribute: :linenos: + context="*" + view=".views.hello_world" + name="hello.html" + /> This indicates that when :app:`Pyramid` identifies that the :term:`view name` is ``hello.html`` and the context is of any type, @@ -654,9 +656,9 @@ declaration` causes a route to be added to the application. :linenos: .. note:: @@ -705,9 +707,9 @@ absolute path. :linenos: + name="static" + path="/var/www/static" + /> Here's an example of a ``static`` directive that will serve files up under the ``/static`` URL from the ``a/b/c/static`` directory of the @@ -718,9 +720,9 @@ Python package named ``some_package`` using a fully qualified :linenos: + name="static" + path="some_package:a/b/c/static" + /> Here's an example of a ``static`` directive that will serve files up under the ``/static`` URL from the ``static`` directory of the Python @@ -731,9 +733,9 @@ package-relative path. :linenos: + name="static" + path="static" + /> Whether you use for ``path`` a fully qualified resource specification, an absolute path, or a package-relative path, When you place your @@ -764,9 +766,9 @@ argument which is ``http://example.com/images``: :linenos: + name="http://example.com/images" + path="mypackage:images" + /> Because the ``static`` ZCML directive is provided with a ``name`` argument that is the URL prefix ``http://example.com/images``, subsequent calls to @@ -808,7 +810,7 @@ this: + secret="iamsosecret"/> @@ -852,16 +854,16 @@ An example of its usage, with all attributes fully expanded: :linenos: See :ref:`authtktauthenticationpolicy_directive` for details about @@ -880,8 +882,8 @@ An example of its usage, with all attributes fully expanded: :linenos: See :ref:`remoteuserauthenticationpolicy_directive` for detailed @@ -900,8 +902,8 @@ An example of its usage, with all attributes fully expanded: :linenos: See :ref:`repozewho1authenticationpolicy_directive` for detailed @@ -953,7 +955,8 @@ For example, to add a renderer which renders views which have a + factory="my.package.MyJinja2Renderer" + /> The ``factory`` attribute is a :term:`dotted Python name` that must point to an implementation of a :term:`renderer factory`. @@ -972,7 +975,8 @@ See :ref:`adding_a_renderer` for more information for the definition of a + factory="my.package.MyAMFRenderer" + /> Adding the above ZCML to your application will allow you to use the ``my.package.MyAMFRenderer`` renderer factory implementation in view @@ -983,8 +987,9 @@ attribute of a :term:`view configuration`: :linenos: + view="mypackage.views.my_view" + renderer="amf" + /> Here's an example of the registration of a more complicated renderer factory, which expects to be passed a filesystem path: @@ -994,7 +999,8 @@ factory, which expects to be passed a filesystem path: + factory="my.package.MyJinja2Renderer" + /> Adding the above ZCML to your application will allow you to use the ``my.package.MyJinja2Renderer`` renderer factory implementation in @@ -1006,8 +1012,9 @@ configuration`: :linenos: + view="mypackage.views.my_view" + renderer="templates/mytemplate.jinja2" + /> When a :term:`view configuration` which has a ``name`` attribute that does contain a dot, such as ``templates/mytemplate.jinja2`` above is encountered at @@ -1038,8 +1045,9 @@ renderer factory, use: :linenos: + name=".zpt" + factory="pyramid.chameleon_zpt.renderer_factory" + /> After you do this, :app:`Pyramid` will treat templates ending in both the ``.pt`` and ``.zpt`` filename extensions as Chameleon ZPT @@ -1053,8 +1061,9 @@ a variation on the following in your application's ZCML: :linenos: + name=".pt" + factory="my.package.pt_renderer" + /> After you do this, the :term:`renderer factory` in ``my.package.pt_renderer`` will be used to render templates which end @@ -1068,8 +1077,9 @@ variation on the following in your application's ZCML: :linenos: + name=".txt" + factory="my.package.text_renderer" + /> After you do this, the :term:`renderer factory` in ``my.package.text_renderer`` will be used to render templates which @@ -1084,7 +1094,8 @@ tag): :linenos: + factory="pyramid.renderers.json_renderer_factory" + /> See also :ref:`renderer_directive` and :meth:`pyramid.configuration.Configurator.add_renderer`. @@ -1123,7 +1134,8 @@ You can add a custom locale negotiator via ZCML by using the :linenos: + negotiator="my_application.my_module.my_locale_negotiator" + /> See also :ref:`custom_locale_negotiator` and :ref:`localenegotiator_directive`. @@ -1145,8 +1157,8 @@ which we assume lives in a ``subscribers.py`` module within your application: :linenos: See also :ref:`subscriber_directive` and :ref:`events_chapter`. diff --git a/docs/narr/environment.rst b/docs/narr/environment.rst index c3fe401ec..814cb70d6 100644 --- a/docs/narr/environment.rst +++ b/docs/narr/environment.rst @@ -278,6 +278,7 @@ Setting Name" column would go in the ``[app:main]`` section. Here's an example of such a section: .. code-block:: ini + :linenos: [app:main] use = egg:MyProject#app @@ -288,7 +289,8 @@ You can also use environment variables to accomplish the same purpose for settings documented as such. For example, you might start your :app:`Pyramid` application using the following command line: -.. code-block:: python +.. code-block:: text + :linenos: $ BFG_DEBUG_AUTHORIZATION=1 BFG_RELOAD_TEMPLATES=1 bin/paster serve \ MyProject.ini diff --git a/docs/narr/extending.rst b/docs/narr/extending.rst index 49de50722..902fb001d 100644 --- a/docs/narr/extending.rst +++ b/docs/narr/extending.rst @@ -190,9 +190,10 @@ the original application with slight tweaks. For example: .. code-block:: xml :linenos: - A similar pattern can be used to *extend* the application with diff --git a/docs/narr/firstapp.rst b/docs/narr/firstapp.rst index 9d3cad13c..17140fe07 100644 --- a/docs/narr/firstapp.rst +++ b/docs/narr/firstapp.rst @@ -47,7 +47,7 @@ When this code is inserted into a Python script named ``helloworld.py`` and executed by a Python interpreter which has the :app:`Pyramid` software installed, an HTTP server is started on TCP port 8080: -.. code-block:: bash +.. code-block:: text $ python helloworld.py serving on 0.0.0.0:8080 view at http://127.0.0.1:8080 diff --git a/docs/narr/hooks.rst b/docs/narr/hooks.rst index 2bb66e559..ada96f897 100644 --- a/docs/narr/hooks.rst +++ b/docs/narr/hooks.rst @@ -54,7 +54,8 @@ class as the ``context`` of the view configuration. + context="pyramid.exceptions.NotFound" + /> Replace ``helloworld.views.notfound_view`` with the Python dotted name to the notfound view you want to use. @@ -142,7 +143,8 @@ class as the ``context`` of the view configuration. + context="pyramid.exceptions.Forbidden" + /> Replace ``helloworld.views.forbidden_view`` with the Python dotted name to the forbidden view you want to use. @@ -203,7 +205,7 @@ change the default traverser: factory="myapp.traversal.Traverser" provides="pyramid.interfaces.ITraverser" for="*" - /> + /> In the example above, ``myapp.traversal.Traverser`` is assumed to be a class that implements the following interface: @@ -254,7 +256,7 @@ traverser would be used. For example: factory="myapp.traversal.Traverser" provides="pyramid.interfaces.ITraverser" for="myapp.models.MyRoot" - /> + /> If the above stanza was added to a ``configure.zcml`` file, :app:`Pyramid` would use the ``myapp.traversal.Traverser`` only @@ -287,7 +289,7 @@ of :term:`context` by adding an adapter stanza for factory="myapp.traversal.URLGenerator" provides="pyramid.interfaces.IContextURL" for="myapp.models.MyRoot *" - /> + /> In the above example, the ``myapp.traversal.URLGenerator`` class will be used to provide services to :func:`pyramid.url.model_url` any diff --git a/docs/narr/i18n.rst b/docs/narr/i18n.rst index 9e2071872..f6f3cdc42 100644 --- a/docs/narr/i18n.rst +++ b/docs/narr/i18n.rst @@ -104,7 +104,9 @@ right translator file on the filesystem which contains translations for a given domain. In this case, if it were trying to translate our msgid to German, it might try to find a translation from a :term:`gettext` file within a :term:`translation directory` like this -one:: +one: + +.. code-block:: text locale/de/LC_MESSAGES/form.mo @@ -268,7 +270,7 @@ If the :term:`virtualenv` into which you've installed your :app:`Pyramid` application lives in ``/my/virtualenv``, you can install Babel like so: -.. code-block:: bash +.. code-block:: text $ cd /my/virtualenv $ bin/easy_install Babel @@ -280,7 +282,7 @@ If the :term:`virtualenv` into which you've installed your :app:`Pyramid` application lives in ``C:\my\virtualenv``, you can install Babel like so: -.. code-block:: bash +.. code-block:: text C> cd \my\virtualenv C> bin\easy_install Babel @@ -307,9 +309,9 @@ In particular, add the ``Babel`` distribution to the :linenos: setup(name="mypackage", - ... + # ... install_requires = [ - .... + # ... 'Babel', ], message_extractors = { '.': [ @@ -336,7 +338,7 @@ message catalog template from the code and :term:`Chameleon` templates which reside in your :app:`Pyramid` application. You run a ``setup.py`` command to extract the messages: -.. code-block:: bash +.. code-block:: text :linenos: $ cd /place/where/myapplication/setup.py/lives @@ -424,7 +426,10 @@ in the ``.pot`` file, you need to generate at least one ``.po`` file. A ``.po`` file represents translations of a particular set of messages to a particular locale. Initialize a ``.po`` file for a specific locale from a pre-generated ``.pot`` template by using the ``setup.py -init_catalog`` command:: +init_catalog`` command: + +.. code-block:: text + :linenos: $ cd /place/where/myapplication/setup.py/lives $ python setup.py init_catalog -l es @@ -455,7 +460,8 @@ changed messages can also be translated or re-translated. First, regenerate the ``.pot`` file as per :ref:`extracting_messages`. Then use the ``setup.py update_catalog`` command. -.. code-block:: bash +.. code-block:: text + :linenos: $ cd /place/where/myapplication/setup.py/lives $ python setup.py update_catalog @@ -469,7 +475,10 @@ Compiling a Message Catalog File ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Finally, to prepare an application for performing actual runtime -translations, compile ``.po`` files to ``.mo`` files:: +translations, compile ``.po`` files to ``.mo`` files: + +.. code-block:: text + :linenos: $ cd /place/where/myapplication/setup.py/lives $ python setup.py compile_catalog @@ -812,16 +821,18 @@ mechanism: Allow a deployer to modify your application's PasteDeploy .ini file: .. code-block:: ini + :linenos: [app:main] use = egg:MyProject#app - ... + # ... available_languages = fr de en ru Then as a part of the code of a custom :term:`locale negotiator`: -.. code-block:: py - +.. code-block:: python + :linenos: + from pyramid.threadlocal import get_current_registry settings = get_current_registry().settings languages = settings['available_languages'].split() @@ -877,7 +888,7 @@ application startup. For example: config.begin() config.add_translation_dirs('my.application:locale/', 'another.application:locale/') - ... + # ... config.end() A message catalog in a translation directory added via diff --git a/docs/narr/resources.rst b/docs/narr/resources.rst index e98c34595..3ff8af90b 100644 --- a/docs/narr/resources.rst +++ b/docs/narr/resources.rst @@ -259,7 +259,7 @@ override a single resource. For example: + /> The string value passed to both ``to_override`` and ``override_with`` attached to a resource directive is called a "specification". The diff --git a/docs/narr/security.rst b/docs/narr/security.rst index 8cf459880..782dbffb1 100644 --- a/docs/narr/security.rst +++ b/docs/narr/security.rst @@ -497,7 +497,9 @@ Debugging View Authorization Failures If your application in your judgment is allowing or denying view access inappropriately, start your application under a shell using the ``BFG_DEBUG_AUTHORIZATION`` environment variable set to ``1``. For -example:: +example: + +.. code-block:: text $ BFG_DEBUG_AUTHORIZATION=1 bin/paster serve myproject.ini @@ -508,7 +510,9 @@ authentication information. This behavior can also be turned on in the application ``.ini`` file by setting the ``debug_authorization`` key to ``true`` within the -application's configuration section, e.g.:: +application's configuration section, e.g.: + +.. code-block:: guess [app:main] use = egg:MyProject#app diff --git a/docs/narr/startup.rst b/docs/narr/startup.rst index 427acc319..9103bf20f 100644 --- a/docs/narr/startup.rst +++ b/docs/narr/startup.rst @@ -68,6 +68,7 @@ press ``return`` after running ``paster serve development.ini``. ``__init__.py`` module: .. literalinclude:: MyProject/myproject/__init__.py + :language: python :linenos: Note that the constructor function accepts a ``global_config`` @@ -83,6 +84,7 @@ press ``return`` after running ``paster serve development.ini``. Our generated ``development.ini`` file looks like so: .. literalinclude:: MyProject/development.ini + :language: guess :linenos: In this case, the ``myproject.run:app`` function referred to by the entry diff --git a/docs/narr/templates.rst b/docs/narr/templates.rst index f7929b44e..e11f69ab1 100644 --- a/docs/narr/templates.rst +++ b/docs/narr/templates.rst @@ -543,7 +543,9 @@ you can create templates that are entirely composed of text except for Here's an example usage of a Chameleon text template. Create a file on disk named ``mytemplate.txt`` in your project's ``templates`` -directory with the following contents:: +directory with the following contents: + +.. code-block:: text Hello, ${name}! @@ -590,7 +592,7 @@ should cause it to ignore these files. Here's the contents of the author's ``svn propedit svn:ignore .`` in each of my ``templates`` directories. -.. code-block:: bash +.. code-block:: text :linenos: *.pt.py @@ -620,13 +622,17 @@ environment variable setting or a configuration file setting. To use an environment variable, start your application under a shell using the ``BFG_DEBUG_TEMPLATES`` operating system environment -variable set to ``1``, For example:: +variable set to ``1``, For example: + +.. code-block:: text $ BFG_DEBUG_TEMPLATES=1 bin/paster serve myproject.ini To use a setting in the application ``.ini`` file for the same purpose, set the ``debug_templates`` key to ``true`` within the -application's configuration section, e.g.:: +application's configuration section, e.g.: + +.. code-block:: guess [app:main] use = egg:MyProject#app @@ -634,7 +640,9 @@ application's configuration section, e.g.:: With template debugging off, a :exc:`NameError` exception resulting from rendering a template with an undefined variable -(e.g. ``${wrong}``) might end like this:: +(e.g. ``${wrong}``) might end like this: + +.. code-block:: python File "...", in __getitem__ raise NameError(key) @@ -642,7 +650,9 @@ from rendering a template with an undefined variable Note that the exception has no information about which template was being rendered when the error occured. But with template debugging -on, an exception resulting from the same problem might end like so:: +on, an exception resulting from the same problem might end like so: + +.. code-block:: text RuntimeError: Caught exception rendering template. - Expression: ``wrong`` @@ -774,13 +784,17 @@ environment variable setting or a configuration file setting. To use an environment variable, start your application under a shell using the ``BFG_RELOAD_TEMPLATES`` operating system environment -variable set to ``1``, For example:: +variable set to ``1``, For example: + +.. code-block:: text $ BFG_RELOAD_TEMPLATES=1 bin/paster serve myproject.ini To use a setting in the application ``.ini`` file for the same purpose, set the ``reload_templates`` key to ``true`` within the -application's configuration section, e.g.:: +application's configuration section, e.g.: + +.. code-block:: guess [app:main] use = egg:MyProject#app diff --git a/docs/narr/traversal.rst b/docs/narr/traversal.rst index 56594ed5a..40c7503de 100644 --- a/docs/narr/traversal.rst +++ b/docs/narr/traversal.rst @@ -403,7 +403,9 @@ Let's pretend the user asks for ``http://example.com/foo/bar/baz/biz/buz.txt``. The request's ``PATH_INFO`` in that case is ``/foo/bar/baz/biz/buz.txt``. Let's further pretend that when this request comes in that we're traversing -the following object graph:: +the following object graph: + +.. code-block:: text /-- | @@ -448,7 +450,9 @@ Let's say that view lookup finds no matching view type. In this circumstance, the :app:`Pyramid` :term:`router` returns the result of the :term:`not found view` and the request ends. -However, for this graph:: +However, for this graph: + +.. code-block:: text /-- | diff --git a/docs/narr/urldispatch.rst b/docs/narr/urldispatch.rst index df7d592f9..0fc7d22af 100644 --- a/docs/narr/urldispatch.rst +++ b/docs/narr/urldispatch.rst @@ -350,7 +350,9 @@ also capture the remainder of the URL, for example: foo/{baz}/{bar}{fizzle:.*} The above pattern will match these URLs, generating the following -matchdicts:: +matchdicts: + +.. code-block:: text foo/1/2/ -> {'baz':'1', 'bar':'2', 'fizzle':()} foo/abc/def/a/b/c -> {'baz':'abc', 'bar':'def', 'fizzle': 'a/b/c')} diff --git a/docs/narr/vhosting.rst b/docs/narr/vhosting.rst index 0f0fd0d4d..d120e48f6 100644 --- a/docs/narr/vhosting.rst +++ b/docs/narr/vhosting.rst @@ -40,13 +40,14 @@ Here's an example of a PasteDeploy configuration snippet that includes a ``urlmap`` composite. .. code-block:: ini + :linenos: [app:mypyramidapp] use = egg:mypyramidapp#app [composite:main] use = egg:Paste#urlmap - /pyramidapp = mypyramidapp + pyramidapp = mypyramidapp This "roots" the :app:`Pyramid` application at the prefix ``/pyramidapp`` and serves up the composite as the "main" application diff --git a/docs/narr/views.rst b/docs/narr/views.rst index c82dd2cb2..9a42bb177 100644 --- a/docs/narr/views.rst +++ b/docs/narr/views.rst @@ -469,7 +469,7 @@ You can configure a view to use the JSON renderer by naming ``json`` as the :linenos: config.add_view('myproject.views.hello_world', - name='hello' + name='hello', context='myproject.models.Hello', renderer='json') diff --git a/docs/narr/zca.rst b/docs/narr/zca.rst index cf05f39ed..7c7617a3d 100644 --- a/docs/narr/zca.rst +++ b/docs/narr/zca.rst @@ -115,6 +115,7 @@ registry, the following bit of code is equivalent to ``zope.component.getUtility(IFoo)``: .. code-block:: python + :linenos: registry.getUtility(IFoo) -- cgit v1.2.3 From b4981cf3808d32a6de5cb265b225723806aa4094 Mon Sep 17 00:00:00 2001 From: Blaise Laflamme Date: Sun, 28 Nov 2010 02:31:17 -0500 Subject: Fixed typos in vhosting --- docs/narr/vhosting.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/narr') diff --git a/docs/narr/vhosting.rst b/docs/narr/vhosting.rst index d120e48f6..d1fd1b382 100644 --- a/docs/narr/vhosting.rst +++ b/docs/narr/vhosting.rst @@ -47,7 +47,7 @@ a ``urlmap`` composite. [composite:main] use = egg:Paste#urlmap - pyramidapp = mypyramidapp + /pyramidapp = mypyramidapp This "roots" the :app:`Pyramid` application at the prefix ``/pyramidapp`` and serves up the composite as the "main" application -- cgit v1.2.3 From be51e0cb03d2c0d339f6bc9318f1008688c6a23a Mon Sep 17 00:00:00 2001 From: Blaise Laflamme Date: Sun, 28 Nov 2010 02:47:38 -0500 Subject: Updated traversal and router diagrams --- docs/narr/modelgraphtraverser.png | Bin 158471 -> 232233 bytes docs/narr/router.png | Bin 170820 -> 177022 bytes 2 files changed, 0 insertions(+), 0 deletions(-) (limited to 'docs/narr') diff --git a/docs/narr/modelgraphtraverser.png b/docs/narr/modelgraphtraverser.png index 053bb9913..037d12b18 100644 Binary files a/docs/narr/modelgraphtraverser.png and b/docs/narr/modelgraphtraverser.png differ diff --git a/docs/narr/router.png b/docs/narr/router.png index 229fb5cd5..606495f13 100644 Binary files a/docs/narr/router.png and b/docs/narr/router.png differ -- cgit v1.2.3 From 16cd50c1a5beef98c3297d105c1ccffccb8872c5 Mon Sep 17 00:00:00 2001 From: Blaise Laflamme Date: Sun, 28 Nov 2010 12:28:30 -0500 Subject: Normalized narrative doc, code with linenos while text+bash don't --- docs/narr/configuration.rst | 1 + docs/narr/declarative.rst | 1 - docs/narr/environment.rst | 1 - docs/narr/firstapp.rst | 2 ++ docs/narr/handlers.rst | 8 ++++++++ docs/narr/i18n.rst | 4 ---- docs/narr/install.rst | 4 ++-- docs/narr/models.rst | 1 + docs/narr/project.rst | 5 ++++- docs/narr/security.rst | 6 +++++- docs/narr/static.rst | 1 + docs/narr/templates.rst | 9 +++++---- docs/narr/urldispatch.rst | 1 + docs/narr/views.rst | 2 ++ docs/narr/webob.rst | 2 ++ 15 files changed, 34 insertions(+), 14 deletions(-) (limited to 'docs/narr') diff --git a/docs/narr/configuration.rst b/docs/narr/configuration.rst index ae02a5a6c..ea3a6c866 100644 --- a/docs/narr/configuration.rst +++ b/docs/narr/configuration.rst @@ -142,6 +142,7 @@ method, effectively: .. ignore-next-block .. code-block:: python + :linenos: config.add_view(hello) diff --git a/docs/narr/declarative.rst b/docs/narr/declarative.rst index 3c5eb9db4..eeaed318f 100644 --- a/docs/narr/declarative.rst +++ b/docs/narr/declarative.rst @@ -256,7 +256,6 @@ application we created earlier in :ref:`helloworld_imperative`. We can run it the same way. .. code-block:: text - :linenos: $ python helloworld.py serving on 0.0.0.0:8080 view at http://127.0.0.1:8080 diff --git a/docs/narr/environment.rst b/docs/narr/environment.rst index 814cb70d6..af03077af 100644 --- a/docs/narr/environment.rst +++ b/docs/narr/environment.rst @@ -290,7 +290,6 @@ for settings documented as such. For example, you might start your :app:`Pyramid` application using the following command line: .. code-block:: text - :linenos: $ BFG_DEBUG_AUTHORIZATION=1 BFG_RELOAD_TEMPLATES=1 bin/paster serve \ MyProject.ini diff --git a/docs/narr/firstapp.rst b/docs/narr/firstapp.rst index 17140fe07..c49e788b0 100644 --- a/docs/narr/firstapp.rst +++ b/docs/narr/firstapp.rst @@ -263,6 +263,7 @@ WSGI Application Creation .. ignore-next-block .. code-block:: python + :linenos: app = config.make_wsgi_app() @@ -294,6 +295,7 @@ WSGI Application Serving .. ignore-next-block .. code-block:: python + :linenos: serve(app, host='0.0.0.0') diff --git a/docs/narr/handlers.rst b/docs/narr/handlers.rst index d82f42bdb..0dce6afe4 100644 --- a/docs/narr/handlers.rst +++ b/docs/narr/handlers.rst @@ -37,6 +37,7 @@ will call that view callable. Here's an example view handler class: .. code-block:: python + :linenos: from pyramid.response import Response @@ -58,6 +59,7 @@ An accompanying call to the be performed in order to register it with the system: .. code-block:: python + :linenos: config.add_handler('hello', '/hello/{action}', handler=Hello) @@ -74,6 +76,7 @@ Alternatively, the action can be declared specifically for a URL to go to a specific ``action`` name: .. code-block:: python + :linenos: config.add_handler('hello_index', '/hello/index', handler=Hello, action='index') @@ -97,6 +100,7 @@ directly through to :meth:`pyramid.configuration.Configurator.add_route`. For example: .. code-block:: python + :linenos: config.add_handler('hello', '/hello/{action}', handler='mypackage.handlers:MyHandler') @@ -110,6 +114,7 @@ specify the same handler, to register specific route names for different handler/action combinations. For example: .. code-block:: python + :linenos: config.add_handler('hello_index', '/hello/index', handler=Hello, action='index') @@ -139,6 +144,7 @@ Every method in the handler class that has a name meeting the disabled by setting the ``__autoexpose__`` attribute to ``None``: .. code-block:: python + :linenos: from pyramid.view import action @@ -179,6 +185,7 @@ name that is different from the method name by passing in a ``name`` argument. Example: .. code-block:: python + :linenos: from pyramid.view import action @@ -205,6 +212,7 @@ URL's can result in different template renderings with the same data. Example: .. code-block:: python + :linenos: from pyramid.view import action diff --git a/docs/narr/i18n.rst b/docs/narr/i18n.rst index f6f3cdc42..603b08cef 100644 --- a/docs/narr/i18n.rst +++ b/docs/narr/i18n.rst @@ -339,7 +339,6 @@ which reside in your :app:`Pyramid` application. You run a ``setup.py`` command to extract the messages: .. code-block:: text - :linenos: $ cd /place/where/myapplication/setup.py/lives $ mkdir -p myapplication/locale @@ -429,7 +428,6 @@ locale from a pre-generated ``.pot`` template by using the ``setup.py init_catalog`` command: .. code-block:: text - :linenos: $ cd /place/where/myapplication/setup.py/lives $ python setup.py init_catalog -l es @@ -461,7 +459,6 @@ First, regenerate the ``.pot`` file as per :ref:`extracting_messages`. Then use the ``setup.py update_catalog`` command. .. code-block:: text - :linenos: $ cd /place/where/myapplication/setup.py/lives $ python setup.py update_catalog @@ -478,7 +475,6 @@ Finally, to prepare an application for performing actual runtime translations, compile ``.po`` files to ``.mo`` files: .. code-block:: text - :linenos: $ cd /place/where/myapplication/setup.py/lives $ python setup.py compile_catalog diff --git a/docs/narr/install.rst b/docs/narr/install.rst index c753b7298..db1cfaf9d 100644 --- a/docs/narr/install.rst +++ b/docs/narr/install.rst @@ -334,7 +334,7 @@ The ``pyramid_jinja2`` distribution provides templating for :app:`Pyramid` using the :term:`Jinja2` templating system. You may install it like so using the ``easy_install`` command for Jython: -.. code-block:: python +.. code-block:: text $ easy_install pyramid_jinja2 @@ -342,7 +342,7 @@ Once this is done, you can use this command to get started with a :app:`Pyramid` sample application that uses the Jinja2 templating engine: -.. code-block:: python +.. code-block:: text $ paster create -t pyramid_jinja2_starter diff --git a/docs/narr/models.rst b/docs/narr/models.rst index f8488cc80..20f443571 100644 --- a/docs/narr/models.rst +++ b/docs/narr/models.rst @@ -272,6 +272,7 @@ The ``__parent__`` of the root object should be ``None`` and its ``__name__`` should be the empty string. For instance: .. code-block:: python + :linenos: class MyRootObject(object): __name__ = '' diff --git a/docs/narr/project.rst b/docs/narr/project.rst index 1758e9d00..b2b0931b6 100644 --- a/docs/narr/project.rst +++ b/docs/narr/project.rst @@ -257,7 +257,7 @@ points to *your application* as opposed to any other section within the ``.ini`` file. For example, if your application ``.ini`` file might have a ``[app:MyProject]`` section that looks like so: -.. code-block:: guess +.. code-block:: ini :linenos: [app:MyProject] @@ -930,6 +930,7 @@ Then change the __init__.py of your myproject project (*not* the parent directory). For example, from something like: .. code-block:: python + :linenos: config.add_view('myproject.views.my_view', renderer='myproject:templates/mytemplate.pt') @@ -937,6 +938,7 @@ parent directory). For example, from something like: To this: .. code-block:: python + :linenos: config.add_view('myproject.views.blogs.my_view', renderer='myproject:templates/mytemplate.pt') @@ -946,6 +948,7 @@ views or handler classes/functions within those files via the dotted name passed as the first argument to ``add_view``. For example: .. code-block:: python + :linenos: config.add_view('myproject.views.anothermodule.my_view', renderer='myproject:templates/anothertemplate.pt') diff --git a/docs/narr/security.rst b/docs/narr/security.rst index 782dbffb1..2c696772a 100644 --- a/docs/narr/security.rst +++ b/docs/narr/security.rst @@ -436,6 +436,7 @@ authorization policy is in effect might look like so: the following: .. code-block:: python + :linenos: from pyramid.security import ALL_PERMISSIONS __acl__ = [ (Deny, Everyone, ALL_PERMISSIONS) ] @@ -512,7 +513,8 @@ This behavior can also be turned on in the application ``.ini`` file by setting the ``debug_authorization`` key to ``true`` within the application's configuration section, e.g.: -.. code-block:: guess +.. code-block:: ini + :linenos: [app:main] use = egg:MyProject#app @@ -555,6 +557,7 @@ authenticate. Doing so is a matter of creating an instance of something that implements the following interface: .. code-block:: python + :linenos: class AuthenticationPolicy(object): """ An object representing a Pyramid authentication policy. """ @@ -610,6 +613,7 @@ matter of creating an instance of an object that implements the following interface: .. code-block:: python + :linenos: class IAuthorizationPolicy(object): """ An object representing a Pyramid authorization policy. """ diff --git a/docs/narr/static.rst b/docs/narr/static.rst index a01cbbabf..beb12c586 100644 --- a/docs/narr/static.rst +++ b/docs/narr/static.rst @@ -185,6 +185,7 @@ resources which begin with ``mypackage:images`` will be prefixed with ``http://example.com/images``: .. code-block:: python + :linenos: static_url('mypackage:images/logo.png', request) # -> http://example.com/images/logo.png diff --git a/docs/narr/templates.rst b/docs/narr/templates.rst index e11f69ab1..c1c2fe31e 100644 --- a/docs/narr/templates.rst +++ b/docs/narr/templates.rst @@ -593,7 +593,6 @@ author's ``svn propedit svn:ignore .`` in each of my ``templates`` directories. .. code-block:: text - :linenos: *.pt.py *.txt.py @@ -632,7 +631,8 @@ To use a setting in the application ``.ini`` file for the same purpose, set the ``debug_templates`` key to ``true`` within the application's configuration section, e.g.: -.. code-block:: guess +.. code-block:: ini + :linenos: [app:main] use = egg:MyProject#app @@ -642,7 +642,7 @@ With template debugging off, a :exc:`NameError` exception resulting from rendering a template with an undefined variable (e.g. ``${wrong}``) might end like this: -.. code-block:: python +.. code-block:: text File "...", in __getitem__ raise NameError(key) @@ -794,7 +794,8 @@ To use a setting in the application ``.ini`` file for the same purpose, set the ``reload_templates`` key to ``true`` within the application's configuration section, e.g.: -.. code-block:: guess +.. code-block:: ini + :linenos: [app:main] use = egg:MyProject#app diff --git a/docs/narr/urldispatch.rst b/docs/narr/urldispatch.rst index 0fc7d22af..b025ce8d6 100644 --- a/docs/narr/urldispatch.rst +++ b/docs/narr/urldispatch.rst @@ -1143,6 +1143,7 @@ custom notfound view as the first argument to its constructor. For instance: .. code-block:: python + :linenos: from pyramid.exceptions import NotFound from pyramid.view import AppendSlashNotFoundViewFactory diff --git a/docs/narr/views.rst b/docs/narr/views.rst index 9a42bb177..04d90fda8 100644 --- a/docs/narr/views.rst +++ b/docs/narr/views.rst @@ -1459,6 +1459,7 @@ configuration stanza: .. ignore-next-block .. code-block:: python + :linenos: config.add_view('.views.my_view', name='my_view', request_method='POST', context=MyModel, permission='read') @@ -1488,6 +1489,7 @@ view configuration. To make :app:`Pyramid` process your ``scan`` method of a :class:`pyramid.configuration.Configurator`: .. code-block:: python + :linenos: # config is assumed to be an instance of the # pyramid.configuration.Configurator class diff --git a/docs/narr/webob.rst b/docs/narr/webob.rst index 17827fac9..92de9d409 100644 --- a/docs/narr/webob.rst +++ b/docs/narr/webob.rst @@ -288,6 +288,7 @@ Generally any attribute of the response can be passed in as a keyword argument to the class; e.g.: .. code-block:: python + :linenos: from pyramid.response import Response response = Response(body='hello world!', content_type='text/plain') @@ -316,6 +317,7 @@ the same way. A typical example is: .. ignore-next-block .. code-block:: python + :linenos: from pyramid.httpexceptions import HTTPNotFound from pyramid.httpexceptions import HTTPMovedPermanently -- cgit v1.2.3 From 6942961545fd909bbb6d16a1ab7992351b1586e6 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Wed, 1 Dec 2010 11:09:50 -0500 Subject: fix bad info in urldispatch chapter: matchdict and matched_route will be None --- docs/narr/urldispatch.rst | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) (limited to 'docs/narr') diff --git a/docs/narr/urldispatch.rst b/docs/narr/urldispatch.rst index b025ce8d6..e439c71cd 100644 --- a/docs/narr/urldispatch.rst +++ b/docs/narr/urldispatch.rst @@ -838,8 +838,8 @@ strings. The values will be Unicode objects. .. note:: - If no route URL pattern matches, no ``matchdict`` is attached to - the request. + If no route URL pattern matches, the ``matchdict`` object attached to the + request will be ``None``. .. index:: single: matched_route @@ -857,6 +857,11 @@ an attribute of the :term:`request` object. Thus, request. The most useful attribute of the route object is ``name``, which is the name of the route that matched. +.. note:: + + If no route URL pattern matches, the ``matched_route`` object attached to + the request will be ``None``. + Routing Examples ---------------- -- cgit v1.2.3 From db312f843a83f7959ffa208f46c95e9a7d2c41fb Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Wed, 1 Dec 2010 11:13:31 -0500 Subject: stray quote mark --- docs/narr/hybrid.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/narr') diff --git a/docs/narr/hybrid.rst b/docs/narr/hybrid.rst index e704463c7..df8d72ef4 100644 --- a/docs/narr/hybrid.rst +++ b/docs/narr/hybrid.rst @@ -262,7 +262,7 @@ to do. :class:`pyramid.configuration.Configurator` constructor instead of associating it with a particular route inside the route's configuration. Every hybrid route configuration that is matched but - which does *not* name a ``factory``` attribute will use the use + which does *not* name a ``factory`` attribute will use the use global ``root_factory`` function to generate a root object. When the route configuration named ``home`` above is matched during a -- cgit v1.2.3 From 1220f3b8f869e4caf298d9acb5e5fffe0a86129e Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Wed, 1 Dec 2010 11:20:01 -0500 Subject: explain what reload_templates means wrt individual templating engines --- docs/narr/environment.rst | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) (limited to 'docs/narr') diff --git a/docs/narr/environment.rst b/docs/narr/environment.rst index af03077af..44e75542c 100644 --- a/docs/narr/environment.rst +++ b/docs/narr/environment.rst @@ -38,7 +38,10 @@ application-specific configuration settings. Reloading Templates ------------------- -When this value is true, reload templates without a restart. +When this value is true, reload templates without a restart, so you can see +changes to templates take effect immediately during development. This flag +is meaningful to Chameleon and Mako templates, as well as most third-party +template rendering extensions. +---------------------------------+-----------------------------+ | Environment Variable Name | Config File Setting Name | -- cgit v1.2.3