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') 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