[Repoze-checkins] r1453 - in repoze.bfg/trunk/docs: . narr

Paul Everitt paul at agendaless.com
Thu Jul 24 15:56:57 EDT 2008 

Author: Paul Everitt <paul at agendaless.com>
Date: Thu Jul 24 15:56:57 2008
New Revision: 1453

Log:
Change more occurrences to mod:repoze

Modified:
   repoze.bfg/trunk/docs/glossary.rst
   repoze.bfg/trunk/docs/narr/install.rst
   repoze.bfg/trunk/docs/narr/models.rst
   repoze.bfg/trunk/docs/narr/project.rst
   repoze.bfg/trunk/docs/narr/templates.rst
   repoze.bfg/trunk/docs/narr/traversal.rst
   repoze.bfg/trunk/docs/narr/views.rst

Modified: repoze.bfg/trunk/docs/glossary.rst
==============================================================================
--- repoze.bfg/trunk/docs/glossary.rst	(original)
+++ repoze.bfg/trunk/docs/glossary.rst	Thu Jul 24 15:56:57 2008
@@ -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.

Modified: repoze.bfg/trunk/docs/narr/install.rst
==============================================================================
--- repoze.bfg/trunk/docs/narr/install.rst	(original)
+++ repoze.bfg/trunk/docs/narr/install.rst	Thu Jul 24 15:56:57 2008
@@ -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 @@
 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.

Modified: repoze.bfg/trunk/docs/narr/models.rst
==============================================================================
--- repoze.bfg/trunk/docs/narr/models.rst	(original)
+++ repoze.bfg/trunk/docs/narr/models.rst	Thu Jul 24 15:56:57 2008
@@ -2,8 +2,8 @@
 ======
 
 *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 @@
 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 @@
 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

Modified: repoze.bfg/trunk/docs/narr/project.rst
==============================================================================
--- repoze.bfg/trunk/docs/narr/project.rst	(original)
+++ repoze.bfg/trunk/docs/narr/project.rst	Thu Jul 24 15:56:57 2008
@@ -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 @@
   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 @@
 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 @@
 
 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 @@
 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 @@
 #. 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 @@
 
 #. 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 @@
 ``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 @@
 
 #. 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 @@
 .. 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

Modified: repoze.bfg/trunk/docs/narr/templates.rst
==============================================================================
--- repoze.bfg/trunk/docs/narr/templates.rst	(original)
+++ repoze.bfg/trunk/docs/narr/templates.rst	Thu Jul 24 15:56:57 2008
@@ -8,15 +8,15 @@
 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 @@
 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::

Modified: repoze.bfg/trunk/docs/narr/traversal.rst
==============================================================================
--- repoze.bfg/trunk/docs/narr/traversal.rst	(original)
+++ repoze.bfg/trunk/docs/narr/traversal.rst	Thu Jul 24 15:56:57 2008
@@ -13,7 +13,7 @@
 
 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 @@
 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 @@
 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 @@
 
  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 @@
 "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 @@
 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

Modified: repoze.bfg/trunk/docs/narr/views.rst
==============================================================================
--- repoze.bfg/trunk/docs/narr/views.rst	(original)
+++ repoze.bfg/trunk/docs/narr/views.rst	Thu Jul 24 15:56:57 2008
@@ -2,9 +2,9 @@
 =====
 
 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
 -----------------------------

More information about the Repoze-checkins mailing list