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/declarative.rst | 178 +++++++++++++++++++++++++--------------------- 1 file changed, 95 insertions(+), 83 deletions(-) (limited to 'docs/narr/declarative.rst') 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`. -- 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/declarative.rst | 1 - 1 file changed, 1 deletion(-) (limited to 'docs/narr/declarative.rst') 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 -- cgit v1.2.3