diff options
| -rw-r--r-- | docs/glossary.rst | 4 | ||||
| -rw-r--r-- | docs/narr/install.rst | 29 | ||||
| -rw-r--r-- | docs/narr/models.rst | 10 | ||||
| -rw-r--r-- | docs/narr/project.rst | 62 | ||||
| -rw-r--r-- | docs/narr/templates.rst | 15 | ||||
| -rw-r--r-- | docs/narr/traversal.rst | 39 | ||||
| -rw-r--r-- | docs/narr/views.rst | 6 |
7 files changed, 87 insertions, 78 deletions
diff --git a/docs/glossary.rst b/docs/glossary.rst index 8452f915c..5274ef2de 100644 --- a/docs/glossary.rst +++ b/docs/glossary.rst @@ -13,6 +13,10 @@ iterable body), headerlist (representing the http headers sent upstream), and status (representing the http status string). This is the interface defined for ``WebOb`` response objects. + setuptools + `Setuptools <http://peak.telecommunity.com/DevCenter/setuptools>`_ + builds on Python's ``distutils`` to provide easier building, + distribution, and installation of packages. view A "view" is a callable which returns a response object. It should accept two values: context and request. diff --git a/docs/narr/install.rst b/docs/narr/install.rst index 2e7ae9ffb..a6f5d91e2 100644 --- a/docs/narr/install.rst +++ b/docs/narr/install.rst @@ -1,30 +1,28 @@ -Installing ``repoze.bfg`` -========================= +Installing :mod:`repoze.bfg` +============================ How To Install -------------- You will need `Python <http://python.org>`_ version 2.4 or better to -run ``repoze.bfg``. Development of ``repoze.bfg`` is done under -Python 2.4, so is recommended. ``repoze.bfg`` does *not* run under +run :mod:`repoze.bfg`. Development of :mod:`repoze.bfg` is done under +Python 2.4, so is recommended. :mod:`repoze.bfg` does *not* run under any version of Python before 2.4, and does *not* run under Python 3.X. -You may install ``repoze.bfg`` into your Python environment using the -following command:: +You may install :mod:`repoze.bfg` into your Python environment using +the following command:: $ easy_install -i http://dist.repoze.org/lemonade/dev/simple repoze.bfg -You will need `Setuptools -<http://peak.telecommunity.com/DevCenter/setuptools>`_ installed on -within your Python system in order to run the ``easy_install`` -command. +You will need :term:`setuptools` installed on within your Python +system in order to run the ``easy_install`` command. -It is advisable to install ``repoze.bfg`` into a `virtualenv +It is advisable to install :mod:`repoze.bfg` into a `virtualenv <http://pypi.python.org/pypi/virtualenv>`_ in order to obtain isolation from any "system" packages you've got installed in your -Python version (and likewise, to prevent ``repoze.bfg`` from globally -installing versions of packages that are not compatible with your -system Python). +Python version (and likewise, to prevent :mod:`repoze.bfg` from +globally installing versions of packages that are not compatible with +your system Python). What Gets Installed ------------------- @@ -33,3 +31,6 @@ When you ``easy_install`` repoze.bfg, various Zope libraries, WebOb, PasteScript, PasteDeploy, PasteScript, and FormEncode libraries are installed. +Additionally, as shown in the next section, Paster templates will ge +registered with your site packages. These templates make starting a +new :mod:`repoze.bfg` project a breeze. diff --git a/docs/narr/models.rst b/docs/narr/models.rst index c56d8e2f5..addbdd9ea 100644 --- a/docs/narr/models.rst +++ b/docs/narr/models.rst @@ -2,8 +2,8 @@ Models ====== *Models* are typically simple Python classes defined in a module. - Model *instances* make up the graph that ``repoze.bfg`` is willing to - traverse. + Model *instances* make up the graph that :mod:`repoze.bfg` is willing + to traverse. Defining a Model ---------------- @@ -34,8 +34,8 @@ object can implement zero or more interfaces. Defining a Graph of Model Instances ----------------------------------- -``repoze.bfg`` expects to be able to traverse a graph of model -instances. ``repoze.bfg`` imposes the following policy on model +:mod:`repoze.bfg` expects to be able to traverse a graph of model +instances. :mod:`repoze.bfg` imposes the following policy on model instance nodes in the graph: - Nodes which contain other nodes (aka "container" nodes) must supply @@ -51,7 +51,7 @@ instance nodes in the graph: Location-Aware Model Instances ------------------------------ - - For ``repoze.bfg`` security and convenience URL-generation + - For :mod:`repoze.bfg` security and convenience URL-generation functions to work properly against a model instance graph, all nodes in the graph should have two attributes:: ``__parent__`` and ``__name__``. The ``__parent__`` attribute should be a reference diff --git a/docs/narr/project.rst b/docs/narr/project.rst index 9cd3e93d1..10a1548fd 100644 --- a/docs/narr/project.rst +++ b/docs/narr/project.rst @@ -1,15 +1,16 @@ .. _project_narr: -Starting a ``repoze.bfg`` Project -================================= +Starting a :mod:`repoze.bfg` Project +==================================== -You can use ``repoze.bfg`` 's sample application generator to get -started. +You can use :mod:`repoze.bfg` 's sample application generator to get +started. This generator leverages Paste templates to allow creation +of a new project by answering a series of questions. Creating the Project -------------------- -To start a ``repoze.bfg`` project, use the ``paster create`` +To start a :mod:`repoze.bfg` project, use the ``paster create`` facility:: $ paster create -t bfg @@ -41,12 +42,12 @@ facility:: Running /Users/chrism/projects/repoze-devel/bfg/bin/python setup.py egg_info The project will be created in a directory named ``myproject``. That -directory is a setuptools *project* directory from which a Python -setuptools *distribution* can be created. The ``setup.py`` file in -that directory can be used to distribute your application, or install -your application for deployment or development. A sample PasteDeploy -``.ini`` file named ``myproject.ini`` will also be created in the -project directory. You can use this to run your application. +directory is a :term:`setuptools` *project* directory from which a +Python setuptools *distribution* can be created. The ``setup.py`` +file in that directory can be used to distribute your application, or +install your application for deployment or development. A sample +PasteDeploy ``.ini`` file named ``myproject.ini`` will also be created +in the project directory. You can use this to run your application. The main ``myproject`` contains an additional subdirectory (also named ``myproject``) representing a Python pakckage which holds very simple @@ -72,7 +73,8 @@ it can be found and run under a webserver. Running The Tests For Your Application -------------------------------------- -To run unit tests for your application, you should invoke them like so:: +To run unit tests for your application, you should invoke them like +so:: $ python setup.py test -q running test @@ -107,11 +109,11 @@ the generated ``myproject.ini`` configuration file:: It will listen on port 5432. -.. note:: During development, it's often useful to run ``paster serve`` - using its ``--reload`` option. When any Python module your project - uses, changes, it will restart the server, which makes development - easier, as changes to Python code under ``repoze.bfg`` is not put - into effect until the server restarts. +.. note:: During development, it's often useful to run ``paster + serve`` using its ``--reload`` option. When any Python module your + project uses, changes, it will restart the server, which makes + development easier, as changes to Python code under + :mod:`repoze.bfg` is not put into effect until the server restarts. Viewing the Application ----------------------- @@ -123,7 +125,7 @@ Visit http://localhost:5432/ in your browser. You will see:: The Project Structure --------------------- -Our generated ``repoze.bfg`` application is a setuptools *project* +Our generated :mod:`repoze.bfg` application is a setuptools *project* (named ``myproject``), which contains a Python package (which is *also* named ``myproject``; the paster template generates a project which contains a package that shares its name). @@ -196,8 +198,8 @@ contains: #. A ``views.py`` module, which contains view code. These are purely conventions established by the Paster template: -``repoze.bfg`` doesn't insist that you name things in any particular -way. +:mod:`repoze.bfg` doesn't insist that you name things in any +particular way. ``configure.zcml`` ~~~~~~~~~~~~~~~~~~ @@ -211,9 +213,9 @@ like so: #. Lines 1-3 provide the root node and namespaces for the configuration language. ``bfg`` is the namespace for - ``repoze.bfg``-specific configuration directives. + :mod:`repoze.bfg`-specific configuration directives. -#. Line 6 initializes ``repoze.bfg``-specific configuration +#. Line 6 initializes :mod:`repoze.bfg`-specific configuration directives by including it as a package. #. Lines 8-11 register a single view. It is ``for`` model objects @@ -223,9 +225,9 @@ like so: ``views.py`` ~~~~~~~~~~~~ -Much of the heavy lifting in a ``repoze.bfg`` application comes in the -views. Views are the bridge between the content in the model, and the -HTML given back to the browser. +Much of the heavy lifting in a :mod:`repoze.bfg` application comes in +the views. Views are the bridge between the content in the model, and +the HTML given back to the browser. .. literalinclude:: myproject/myproject/views.py :linenos: @@ -259,13 +261,13 @@ for instances of the ``IMyModel`` type. #. Line 11 defines an instance of MyModel as the root. -#. Line 13 is a function that will be called by the ``repoze.bfg`` +#. Line 13 is a function that will be called by the :mod:`repoze.bfg` *Router* for each request when it wants to find the root of the model graph. Conventionally this is called ``get_root``. In a "real" application, the root object would not be such a simple object. Instead, it would be an object that could access some -persistent data store, such as a database. ``repoze.bfg`` doesn't +persistent data store, such as a database. :mod:`repoze.bfg` doesn't make any assumption about which sort of datastore you'll want to use, so the sample application uses an instance of ``MyModel`` to represent the root. @@ -280,9 +282,9 @@ Paste configuration file to do this work for us. .. literalinclude:: myproject/myproject/run.py :linenos: -#. Lines 1 - 7 define a function that returns a ``repoze.bfg`` Router - application. This is meant to be called by the PasteDeploy framework - as a result of running ``paster serve``. +#. Lines 1 - 7 define a function that returns a :mod:`repoze.bfg` + Router application. This is meant to be called by the PasteDeploy + framework as a result of running ``paster serve``. #. Lines 9 - 12 allow this file to serve as a shortcut for executing our program if the ``run.py`` file is executed directly. It starts diff --git a/docs/narr/templates.rst b/docs/narr/templates.rst index 4b74ab652..26cbb7910 100644 --- a/docs/narr/templates.rst +++ b/docs/narr/templates.rst @@ -8,15 +8,15 @@ provided by a *view* in a form that is meaningful for a particular Default Templating With z3c.pt Page Templates ------------------------------------------------ -Like Zope, ``repoze.bfg`` uses Zope Page Templates (ZPT) as its default -templating language. However, ``repoze.bfg`` uses a different -implementation of the ZPT specification: the `z3c.pt +Like Zope, :mod:`repoze.bfg` uses Zope Page Templates (ZPT) as its +default templating language. However, :mod:`repoze.bfg` uses a +different implementation of the ZPT specification: the `z3c.pt <http://pypi.python.org/pypi/z3c.pt>`_ templating engine. This templating engine complies with the `Zope Page Template <http://wiki.zope.org/ZPT/FrontPage>`_ template specification. While ``z3c.pt`` doesn't implement the METAL specification (feature or -drawback, depending on your viewpoint,) it is significantly faster. And -faster, of course, is the zen of ``repoze.bfg``. +drawback, depending on your viewpoint,) it is significantly +faster. And faster, of course, is the zen of :mod:`repoze.bfg`. Given a template named ``foo.html`` in a directory in your application named "templates", you can render the template in a view via:: @@ -41,8 +41,9 @@ before you can see the changes. Templating with XSLT ------------------------ -``repoze.bfg`` also supports XSLT as an optional templating language. -Like ZPT, an XSLT template is loaded once and re-used between requests. +:mod:`repoze.bfg` also supports XSLT as an optional templating +language. Like ZPT, an XSLT template is loaded once and re-used +between requests. Given a template ``foo.xsl`` in the templates directory, you can render an XSLT as follows:: diff --git a/docs/narr/traversal.rst b/docs/narr/traversal.rst index 3e7c6125b..297dc45a5 100644 --- a/docs/narr/traversal.rst +++ b/docs/narr/traversal.rst @@ -13,7 +13,7 @@ code using pattern matching against URL components. Examples: It is however possible to map URLs to code differently, using object graph traversal. The venerable Zope and CherryPy web frameworks offer -graph-traversal-based URL dispatch. ``repoze.bfg`` also provides +graph-traversal-based URL dispatch. :mod:`repoze.bfg` also provides graph-traversal-based dispatch of URLs to code. Graph-traversal based dispatching is useful if you like the URL to be representative of an arbitrary hierarchy of potentially heterogeneous items. @@ -65,7 +65,7 @@ URL-based dispatch. The Model Graph --------------- -Users interact with your ``repoze.bfg``-based application via a +Users interact with your :mod:`repoze.bfg`-based application via a "router", which is itself a WSGI application. At system startup time, the router is configured with a root object from which all traversal will begin. The root object is a mapping object, such as a Python @@ -74,23 +74,24 @@ nodes (these have no ``__getitem__``) or container nodes (these do have a ``__getitem__``). Items contained within the graph are analogous to the concept of -``model`` objects used by many other frameworks (and ``repoze.bfg`` +``model`` objects used by many other frameworks (and :mod:`repoze.bfg` refers to them as models, as well). They are typically instances of classes. Each containerish instance is willing to return a child or raise a KeyError based on a name passed to its ``__getitem__``. No leaf-level instance is required to have a ``__getitem__``. -``repoze.bfg`` traverses the model graph in order to find a *context*. -It then attempts to find a *view* based on the type of the context. +:mod:`repoze.bfg` traverses the model graph in order to find a +*context*. It then attempts to find a *view* based on the type of the +context. -How ``repoze.bfg`` Processes a Request Using Traversal ------------------------------------------------------- +How :mod:`repoze.bfg` Processes a Request Using Traversal +--------------------------------------------------------- -When a user requests a page from your ``repoze.bfg`` -powered +When a user requests a page from your :mod:`repoze.bfg` -powered application, the system uses this algorithm to determine which Python code to execute: - 1. The request for the page is presented to ``repoze.bfg``'s + 1. The request for the page is presented to :mod:`repoze.bfg`'s "router" in terms of a standard WSGI request, which is represented by a WSGI environment and a start_response callable. @@ -148,10 +149,10 @@ code to execute: 8. Armed with the context, the view name, and the subpath, the router performs a view lookup. It attemtps to look up a view - from the ``repoze.bfg`` application registry using the view name - and the context. If a view factory is found, it is called with - the context and the request. It returns a response, which is fed - back upstream. If a view is not found, a generic WSGI + from the :mod:`repoze.bfg` application registry using the view + name and the context. If a view factory is found, it is called + with the context and the request. It returns a response, which + is fed back upstream. If a view is not found, a generic WSGI ``NotFound`` application is constructed. In either case, the result is returned upstream via the WSGI protocol. @@ -245,8 +246,8 @@ Using the "view name" ("buz.txt") and the type, it asks the "application registry" (configured separately, in "configure.zcml") this question: - - Please find me a "view" (controller in some religions) with the name - "buz.txt" that can be used for type ``IBiz``. + - Please find me a "view" (controller in some religions) with the + name "buz.txt" that can be used for type ``IBiz``. Let's say that question is answered "here you go, here'a a bit of code that is willing to deal with that case", and returns a view. It is @@ -256,10 +257,10 @@ as the "request". It returns a response. There are two special cases: - During traversal you will often end up with a "view name" that is - the empty string. This indicates that ``repoze.bfg`` should look up - the *default view*. The default view is a view that is registered - with no name or a view which is registered with a name that equals - the empty string. + the empty string. This indicates that :mod:`repoze.bfg` should look + up the *default view*. The default view is a view that is + registered with no name or a view which is registered with a name + that equals the empty string. - If any path segment element begins with the special characters ``@@`` (think of them as goggles), that segment is considered the diff --git a/docs/narr/views.rst b/docs/narr/views.rst index a349901bb..820f7215d 100644 --- a/docs/narr/views.rst +++ b/docs/narr/views.rst @@ -2,9 +2,9 @@ Views ===== A view is a callable which is called when a a request enters your -application. ``repoze.bfg's`` primary job is to find and call a view -when a request reaches it. The view's return value must implement the -Response object interface. +application. :mod:`repoze.bfg's` primary job is to find and call a +view when a request reaches it. The view's return value must +implement the Response object interface. Defining a View as a Function ----------------------------- |