[Checkins] SVN: bluebream/website/docs/v1.0/ Thanks Garry Steedman for the patch!
Baiju M
baiju.m.mail at gmail.com
Wed Apr 28 11:24:50 EDT 2010
Log message for revision 111542:
Thanks Garry Steedman for the patch!
Changed:
U bluebream/website/docs/v1.0/contributors.rst
U bluebream/website/docs/v1.0/tutorial1.rst
-=-
Modified: bluebream/website/docs/v1.0/contributors.rst
===================================================================
--- bluebream/website/docs/v1.0/contributors.rst 2010-04-28 12:58:13 UTC (rev 111541)
+++ bluebream/website/docs/v1.0/contributors.rst 2010-04-28 15:24:49 UTC (rev 111542)
@@ -38,3 +38,4 @@
- Hermann Himmelbauer
- Paul Harouff
- Saket Srivastav
+- Garry Steedman (IRC nick: birlinn)
Modified: bluebream/website/docs/v1.0/tutorial1.rst
===================================================================
--- bluebream/website/docs/v1.0/tutorial1.rst 2010-04-28 12:58:13 UTC (rev 111541)
+++ bluebream/website/docs/v1.0/tutorial1.rst 2010-04-28 15:24:49 UTC (rev 111542)
@@ -16,15 +16,15 @@
In the :ref:`started-getting` chapter you learned how to install
BlueBream and create a new project using the ``bluebream`` project
-template. In this tutorial, you can learn creating a simple ticket
+template. In this tutorial, you will learn how to create a simple ticket
collector application. This will help you to get more familiar with
the concepts of BlueBream.
-Here is the user stories for the ticket collector application:
+Here are the user stories for the ticket collector application:
1. Any number of tickets can be added to one collector.
-2. Each ticket will be added with a description and one initial
+2. Each new ticket will have a description and one initial
comment.
3. Additional comments can be added to tickets.
@@ -35,7 +35,7 @@
- Understand the project directory structure
- Use Buildout and edit Buildout configuration
- Create content objects and interfaces
-- Use form generation tool (zope.formlib)
+- Use the form generation tool (zope.formlib)
.. note::
@@ -54,9 +54,9 @@
collector application. I will assume that you have already installed
``bluebream`` using the ``easy_install bluebream`` command as
mentioned in the :ref:`started-getting` chapter. We are going to use
-the project name as ``ticketcollector`` and the Python package name
-as ``tc.main``. This will create a project with egg/distribution
-name as ``ticketcollector``, ``tc`` as a namespace package and
+the project name ``ticketcollector`` and the Python package name
+``tc.main``. This will create a project with egg/distribution
+name ``ticketcollector``, ``tc`` as a namespace package and
``main`` as a Python sub-package. Let's create the project directory
layout for ``ticketcollector``::
@@ -90,11 +90,11 @@
3) run: ./bin/buildout
-As you can see above we have provided most of the project details.
+As you can see above, we have provided most of the project details.
The values you provided here may be changed later, however changing
-the Python package name may not be as easy as changing other values.
-Because the Python package name might be referred from many places in
-code later.
+the Python package name may not be as easy as changing other values,
+because the Python package name might be referred to in many places in
+our code later.
Organize the new package
~~~~~~~~~~~~~~~~~~~~~~~~
@@ -107,7 +107,7 @@
buildout.cfg deploy.ini setup.py var/
Once the project directory layout is ready you can add it to your
-version control system. You **should not** add
+version control system. You **should not** add the
``src/ticketcollector.egg-info`` directory as it is generated
automatically by setuptools. Here is an example using `bzr
<http://bazaar.canonical.com/en/>`_::
@@ -129,11 +129,11 @@
Adding the project to a version control system is an optional but
recommended step. You now have a valid source code distribution of
-your project that after building will produce a running application.
+your project that, after building, will produce a running application.
The project is now completely independent of the ``bluebream``
distribution, it's only purpose is to help us get to this point. The
-project now contains all mechanisms required to install the
-dependencies from the Internet and setting up the application.
+project now contains everything required to install the
+dependencies from the Internet and to set-up the application.
Bootstrapping the project
~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -145,10 +145,10 @@
Buildout and to set up the project directory for running it. This
bootstrap script is named ``bootstrap.py`` and will do these things:
-- Download and install ``distribute`` distribution from PyPI which
+- Download and install the ``distribute`` distribution from PyPI which
contains the forked ``setuptools`` Python package inside.
-- Download and install ``zc.buildout`` distribution from PyPI.
+- Download and install the ``zc.buildout`` distribution from PyPI.
- Create the directory structure eg:- bin/ eggs/ parts/ develop-eggs/
@@ -164,23 +164,23 @@
Creating directory '/projects/ticketcollector/eggs'.
Generated script '/projects/ticketcollector/bin/buildout'.
-- The ``bin`` directory is where Buildout install all the executable
+- The ``bin`` directory is where Buildout installs all the executable
scripts.
-- The ``eggs`` directory is where Buildout install Python eggs
+- The ``eggs`` directory is where Buildout installs Python eggs
-- The ``parts`` is where Buildout save all output generated by buildout.
- Buildout expects you to not change anything inside parts directory
+- The ``parts`` is where Buildout saves all output generated by buildout.
+ Buildout expects you to not change anything inside the parts directory
as it is auto generated by Buildout.
-- The ``develop-eggs`` directory is where Buildout save links to all
- locally developped Python eggs.
+- The ``develop-eggs`` directory is where Buildout saves links to all
+ locally developed Python eggs.
Buildout configuration
~~~~~~~~~~~~~~~~~~~~~~
After bootstrapping the project you can build your application. All
-the steps you did so far is only required once per project, but
+the steps you done so far are only required once per project, but
running buildout is required whenever you make changes to the
buildout configuration. You are now ready to run ``bin/buildout`` to
build the application, but before doing this, let's have a look at
@@ -206,11 +206,11 @@
eggs = ticketcollector
The buildout configuration file is divided into multiple sections
-called *parts*. The main part is called ``[buildout]``, and that is
-given as the first part in the above configuration file. Each part
-will be handled by the Buildout plugin mechanism called recipes
-except for ``[buildout]``. ``[buildout]`` is handled specially by
-Buildout as it contains general settings.
+called *parts*. The main part is called ``[buildout]``, and it appears
+as the first part in the listing above. Each part
+will be handled by the Buildout plugin mechanism, called recipes,
+except for ``[buildout]``. ``[buildout]`` is handled as a special
+case by Buildout since it contains general settings.
Let's look at the main ``[buildout]`` part::
@@ -220,25 +220,25 @@
parts = app
test
-The first option (``develop``) tells buildout that, the current
+The first option (``develop``) tells buildout that the current
directory is a Python distribution source, i.e., it contains a
``setup.py`` file. Buildout will inspect the ``setup.py`` and create
a develop egg link inside the ``develop-eggs`` directory. The link
-file should contain path to the location where the Python package is
-residing. So buildout will make sure that the packages is always
-importable. The value of the ``develop`` option could be a relative path
-as given above or absolute path to some directory. You can also add
-multiple lines to ``develop`` option with different paths.
+file should contain the path to the location where the Python package is
+residing. So buildout will make sure that the packages are always
+importable. The value of the ``develop`` option could be a relative path,
+as given above, or absolute path to some directory. You can also add
+multiple lines to the ``develop`` option with different paths.
-The ``extends`` option tells buildout to include the full content of
+The ``extends`` option tells buildout to include the full content of the
``versions.cfg`` file as part the configuration. The
``versions.cfg`` is another Buildout configuration file of the same
format as buildout.cfg and contains the release numbers of different
-dependencies. You can add multiple lines to ``extends`` option to
+dependencies. You can add multiple lines to the ``extends`` option to
include multiple configuration files.
-The ``parts`` option list all the parts to be built by Buildout.
-Buildout expects a recipe for each parts listed here.
+The ``parts`` option lists all the parts to be built by Buildout.
+Buildout expects a recipe for each of the parts listed here.
Now let's look at the ``app`` part::
@@ -254,13 +254,13 @@
This part takes care of all the eggs required for the application to
function. The `zc.recipe.egg
<http://pypi.python.org/pypi/zc.recipe.egg>`_ is an advanced Buildout
-recipe with many features to deal with egg. Majority of the
+recipe with many features for dealing with eggs. Most of the
dependencies will come as part of the main application egg. The
-option ``eggs`` list all the eggs. The first egg,
-``ticketcollector`` is the main locally developing egg. The last
-option, ``interpreter`` specify the name of custom interpreter
+option ``eggs`` lists all the eggs. The first egg,
+``ticketcollector`` is the main locally developed egg. The last
+option, ``interpreter`` specifies the name of the custom interpreter
created by this part. The custom interpreter contains the paths to
-all eggs listed here and its dependencies. So that you can import
+all eggs listed here and their dependencies, so that you can import
any module which is listed as a dependency.
The last part creates the test runner::
@@ -290,27 +290,28 @@
Generated script '/projects/ticketcollector/bin/test'.
In the above example, all eggs are already available in the eggs
-folder, otherwise it will download and install eggs. The buildout
-also created three more scripts inside ``bin`` directory.
+folder. If they are not already available, they will be downloaded
+and installed. The buildout also created three more scripts inside
+the ``bin`` directory.
-- The ``paster`` command can be used to run web server.
+- The ``paster`` command can be used to run a web server.
- The ``breampy`` command provides a custom Python interpreter with
- all eggs included in path.
+ all eggs included in its path.
- The ``test`` command can be used to run the test runner.
-Now we have a project source where we can continue developing this
-application.
+Now we have a project structure which will allow us to continue
+developing our application.
-The PasteDeploy configuration
+PasteDeploy configuration
-----------------------------
BlueBream use WSGI to run the server using PasteDeploy. There are
-two PasteDeploy configure one for deployment (``deploy.ini``) another
-for development (``debug.ini``).
+two PasteDeploy configuration files: one for deployment (``deploy.ini``),
+another for development (``debug.ini``).
-This is the content of ``debug.ini``::
+We will now examine the contents of ``debug.ini``::
[app:main]
use = egg:ticketcollector
@@ -329,8 +330,8 @@
[app:main]
use = egg:ticketcollector
-The ``[app:main]`` section specify the egg to be used. PasteDeploy
-expects a ``paste.app_factory`` entry point defined in the egg. If
+The ``[app:main]`` section specifies the egg to be used. PasteDeploy
+expects a ``paste.app_factory`` entry point to be defined in the egg. If
you look at the ``setup.py`` file, you can see that it is defined
like this::
@@ -339,14 +340,14 @@
The name of entry point should be ``main``. Otherwise, it should be
explicitly mentioned in configuration file. For example, if the
-definition is like this::
+definition is::
[paste.app_factory]
testapp = tc.main.startup:application_factory
The PasteDeploy configuration should be changed like this::
-The second section (``[server:main]``) sepecify the WSGI server::
+The second section (``[server:main]``) specifies the WSGI server::
[server:main]
use = egg:Paste#http
@@ -354,11 +355,10 @@
port = 8080
You can change host name, port and the WSGI server itself from this
-section. In oder to use any other WSGI server, it should included in
-th dependency list in Buildoout configuration.
+section. In oder to use any other WSGI server, it should be included in
+the dependency list in your Buildoout configuration.
-The last section (``[DEFAULT]``) is the place where you can specify
-the default values::
+The last section (``[DEFAULT]``) is where you specify default values::
[DEFAULT]
# set the name of the zope.conf file
@@ -366,11 +366,12 @@
The WSGI application defined in ``tc.main.startup`` expects the
``zope_conf`` option defined in the ``[DEFAULT]`` section. So, this
-option is mandatory. This option specify the path where the main
-zope specific configuration file is residing. The next section
-explains more about the main zope configuration.
+option is mandatory. This option specifies the path of the main
+zope configuration file. We will look at zope configuration in greater
+detail in the next section.
-The ``debug.ini`` add more section useful for debugging::
+The ``debug.ini`` contains configuration options which are useful for
+debugging::
[loggers]
keys = root, wsgi
@@ -434,7 +435,7 @@
# set the name of the debug zope.conf file
zope_conf = %(here)s/etc/zope-debug.conf
-The debug configuration use ``filter-app`` instead of ``app`` to
+The debug configuration uses ``filter-app`` instead of ``app`` to
include WSGI middlewares. Currently only one middleware
(``z3c.evalexception#ajax``) is included. You can look into
PastDeploy documentation for more information about the other
@@ -442,14 +443,13 @@
(``etc/zope-debug.conf``) is different from the deployment
configuration.
-The Zope configuration
+Zope configuration
----------------------
Similar to PasteDeploy configuration, there are two Zope
-configuration files. The one included from ``debug.ini`` and the
-other from ``deploy.ini``.
+configuration files: ``debug.ini`` and ``deploy.ini``.
-This is the content of ``etc/zope.conf`` file::
+This is the content of ``etc/zope.conf``::
# Identify the component configuration used to define the site:
site-definition etc/site.zcml
@@ -490,7 +490,7 @@
From the ``zope.conf`` file, you can specify the main ZCML file to be
loaded (site definition). All paths are specified as relative to
-top-level diretory where PasteDeploy configuration file is residing.
+the top-level directory where the PasteDeploy configuration file resides.
The site definition
-------------------
@@ -551,9 +551,9 @@
</configure>
-The main configuration, ``site.zcml`` include other configuration
-files specific to packages. The ZCML has some directives like
-`include``, ``page``, ``defaultView`` etc. available through various
+The main configuration, ``site.zcml`` contains references to other
+configuration files specific to packages. The ZCML has some directives
+like `include``, ``page``, ``defaultView`` etc. available through various
XML-namespaces. In the ``site.zcml`` the default XML-namespace is
``http://namespaces.zope.org/zope``. If you look at the top of
site.zcml, you can see the XML-namespace refered to like this::
@@ -563,18 +563,20 @@
The ``include`` directive is available in
``http://namespaces.zope.org/zope`` namespace. If you look at other
-configuration files, you can see some other namespaces like
-``http://namespaces.zope.org/browser`` used which has some directives
+configuration files you can see some other namespaces, like
+``http://namespaces.zope.org/browser``, which contains directives
like ``page``.
At the end of ``site.zcml``, project specific configuration files are
-included like this. This will cause to load
-``src/tc/collector/configure.zcml`` file::
+included. For example, the following directive::
<include package="tc.main" />
-Also you can define common configuration for your entire application
-in the ``site.zcml``. The content of ``src/tc/collector/configure.zcml``
+will ensure that the file ``src/tc/collector/configure.zcml`` file is
+loaded.
+
+You can define common configuration for your entire application
+in ``site.zcml``. The content of ``src/tc/collector/configure.zcml``
will look like this::
<configure
@@ -603,17 +605,17 @@
</configure>
-The ``securitypolicy.zcml`` is where you can define the security
-policies. As you can see in the ``configure.zcml``, it includes
+The file ``securitypolicy.zcml`` is where you can define your security
+policies. As you can see in ``configure.zcml``, it includes
``welcome``. By default, if you include a package without mentioning
the configuration file, it will include ``configure.zcml``.
.. _tut1-package-meta-data:
-The package meta-data
+Package meta-data
---------------------
-BlueBream use :term:`Setuptools` to distribute the application
+BlueBream uses :term:`Setuptools` to distribute the application
package. However, you could easily replace it with
:term:`Distribute`.
@@ -683,11 +685,11 @@
""",
)
-Most of the details in the ``setup.py`` is what you're given when
-creating the project from template. In the ``install_requires``
+Most of the details in ``setup.py`` are derived from user input
+when creating the project from a template. In the ``install_requires``
keyword argument, you can list all dependencies for the package.
There are two entry points, the first one is used by PasteDeploy to
-find the WSGI application factory. The second entry point register a
+find the WSGI application factory. The second entry point registers a
sub-command for ``paster`` script named ``shell``.
Running Tests
@@ -698,12 +700,12 @@
automated testing. Along with **zope.testing**, you can use Python's
``unittest`` and ``doctest`` modules. Also there is a functional
testing module called `zope.testbrowser
-<http://pypi.python.org/pypi/zope.testbrowser>`_ . To setup the test
+<http://pypi.python.org/pypi/zope.testbrowser>`_ . To set-up the test
cases, layers etc. BlueBream use the `z3c.testsetup
<http://pypi.python.org/pypi/z3c.testsetup>`_ package.
BlueBream use the Buildout recipe called `zc.recipe.testrunner
-<http://pypi.python.org/pypi/zc.recipe.testrunner>`_ to generate test
+<http://pypi.python.org/pypi/zc.recipe.testrunner>`_ to generate a test
runner script.
If you look at the buildout configuration, you can see the test
@@ -713,7 +715,7 @@
recipe = zc.recipe.testrunner
eggs = ticketcollector
-The testrunner recipe creates a test runner using ``zope.testing``
+The testrunner recipe creates a test runner using the ``zope.testing``
module. The only mandatory option is ``eggs`` where you can specify
the eggs.
@@ -721,7 +723,7 @@
jack at computer:/projects/ticketcollector$ bin/test
-This command will find all the test cases and run it.
+This command will find all the test cases and run them.
.. _tut1-app-object:
@@ -731,10 +733,10 @@
Container objects
~~~~~~~~~~~~~~~~~
-In this section we will explore one of the main concepts in BlueBream
-called **container object**. As mentioned earlier BlueBream use an
+In this section we will explore one of the main concepts in BlueBream:
+ **container objects**. As mentioned earlier BlueBream uses an
object database called ZODB to store your Python objects. You can
-think of an object database as a container which contains objects,
+think of an object database as a container which contains objects;
the inner object may be another container which contains other
objects.
@@ -754,14 +756,14 @@
to make a custom object persistent the object class will have to
inherit from ``persistent.Persistent``.
-Some classes in BlueBream that inherits ``persistent.Persistent``:
+Some classes in BlueBream that inherit from ``persistent.Persistent`` include:
- ``zope.container.btree.BTreeContainer``
- ``zope.container.folder.Folder``
- ``zope.site.folder.Folder``
When you inherit from any of these classes the instances of that
-class will be persistent. The second thing you need to do to make it
+class will be persistent. The second thing you need to do to make objects
persistent is to add the object to an existing container object. You
can experiment with this from the debug shell provided by BlueBream.
But before you try that out create a container class somewhere in
@@ -797,8 +799,8 @@
>>> import transaction
>>> transaction.commit()
-Now you can exit the debug prompt and open it again and see that you
-can access the persistent object again::
+Now if you exit the debug prompt and open it again, you will see that you
+can access the persistent object::
$ ./bin/paster shell debug.ini
...
@@ -829,23 +831,23 @@
As the first step for creating the main application container object
which is going to hold all other objects, you need to create an
-interface. You can name the main application container interface as
+interface. We will name the main application container interface
``ICollector``. To make this interface describe a container object
have it inherit ``zope.container.interfaces.IContainer`` or any
interface derived from it. It is recommended to add a site manager
inside the main application container. In order to add a site
manager later, it is recommend to inherit from
-``zope.site.interfaces.IFolder`` interface. The ``IFolder`` is
-inheriting from ``IContainer``.
+``zope.site.interfaces.IFolder`` interface. The ``IFolder``
+inherits from ``IContainer``.
-You can create a new Python package named ``collector`` inside
-``src/tc`` like this::
+Let's create a new Python package named ``collector`` inside
+``src/tc``::
$ mkdir src/tc/collector
$ echo "# Python Package" > src/tc/collector/__init__.py
-You can create a file named ``src/tc/collector/interfaces.py`` to add
-new interfaces like this::
+You can now create a file named ``src/tc/collector/interfaces.py`` to add
+our interfaces::
from zope.site.interfaces import IFolder
from zope.schema import TextLine
@@ -898,13 +900,13 @@
name = u""
description = u""
-To declare that a class is implementing a particular interface you
+To declare that a class implements a particular interface you
can use the ``implements`` function from ``zope.interface``.
Registering components
~~~~~~~~~~~~~~~~~~~~~~
-Once the interfaces and its implementations are ready you can do the
+Once the interfaces and their implementations are ready you can do the
configuration in ZCML. Open the ``src/tc/collector/configure.zcml``
file for editing and enter the following to declare ``ICollector`` a
content component::
@@ -921,7 +923,7 @@
To set annotations for collector objects we need to configure it as
implementing the ``zope.annotation.interfaces.IAttributeAnnotatable``
-interface. The example configuration below also declare that our
+interface. The example configuration below also declares that our
``Collector`` class implements
``zope.container.interfaces.IContentContainer``. These two classes
are examples of marker interfaces, interfaces used to declare that a
@@ -948,15 +950,15 @@
</class>
The ``class`` directive is a complex directive. There are
-subdirective like ``implements`` and ``require`` below the ``class``
-directive. The above ``class`` directive also declared permission
-setting for ``Collector``.
+subdirectives like ``implements`` and ``require`` below the ``class``
+directive. The ``class`` directive listed above also declares permission
+settings for ``Collector``.
-A view for adding collector
+A view for adding collectors
~~~~~~~~~~~~~~~~~~~~~~~~~~~
Now the content component is ready to use but you will need a web
-page from where to add a ticket collector object. You can use
+page which lets us add a ticket collector object. You can use the
``zope.formlib`` package to create a form view. You can add the view
class definition inside ``src/tc/collector/views.py`` like this::
@@ -1004,7 +1006,7 @@
class="tc.collector.views.AddTicketCollector"
/>
-The package development is completed now but it is not yet included
+The package development is complete now, but it is not yet included
from the main package. To include this package from the main package
(``tc.main``) you need to modify the ``src/tc/main/configure.zcml``
and add this line before ``</configure>``::
@@ -1013,15 +1015,15 @@
Now you can access the URL:
http://localhost:8080/@@add_ticket_collector . It should display a
-form where you can enter details like ``name`` and ``description``.
-You can enter the ``name`` as ``mycollector``, after entering data,
+form where you can enter values for ``name`` and ``description``.
+You can enter the ``name`` as ``mycollector``. After entering your data,
submit the form.
-You can see the file size of ``var/filestorage/Data.fs`` is
-increasing as objects are getting added. The ``Data.fs`` is where
+You can see that the file size of ``var/filestorage/Data.fs``
+increases as objects are added. ``Data.fs`` is where
the persisted objects are physically stored.
-You can also confirm that the object is actually saved into database
+You can also confirm that the object is actually saved into the database
from the Python shell. If you go to the Python shell and try to
access the root object you can see that it has the object you added::
@@ -1048,13 +1050,13 @@
NotFound: Object: <tc.collector.ticketcollector.Collector object at 0x9fe44ac>, name: u'@@index'
This error is raised because there is no view named ``index``
-registered for ``ICollector``. This section will show how to create
-a default view for ``ICollector`` interface.
+registered for ``ICollector``. This section will show you how to create
+a default view for the ``ICollector`` interface.
As you have already seen in the :ref:`started-getting` chapter, you
can create a simple view and register it from ZCML.
-In the ``src/tc/collector/views.py`` add a new view like this::
+In ``src/tc/collector/views.py`` add a new view like this::
class TicketCollectorMainView(form.DisplayForm):
@@ -1076,7 +1078,7 @@
Hello ticket collector!
In the next section you will see more details about the main page for
-collector. We're also going to learn about Zope Page Template.
+collector. We're also going to learn about Zope Page Templates.
.. _tut1-main-page:
@@ -1124,13 +1126,13 @@
-----------
This part of the tutorial covered the basics of creating a web
-application using BlueBream. This chapter narrated in detail about
-the usage of ``bluebream`` paster project template to create a new
-project. This part of the tutorial also walked though the process of
-building application using Buildout. Then narrated creating an
-application container. Finally a default view for the application
+application using BlueBream. We have described in detail how
+to use the ``bluebream`` paster project template to create a new
+project. We have discussed the process of building an application
+using Buildout. We have created an application container. Finally,
+a default view for the application
container was created. :ref:`tut2-tutorial` will expand the
-application with additional functionalities.
+application with additional functionality.
.. raw:: html
More information about the checkins
mailing list