[Checkins] SVN: bluebream/website/docs/v1.0/tutorial1.rst First patch from Daniel Nilsson (Vq)
Baiju M
baiju.m.mail at gmail.com
Sat Mar 6 13:05:42 EST 2010
Log message for revision 109710:
First patch from Daniel Nilsson (Vq)
Changed:
U bluebream/website/docs/v1.0/tutorial1.rst
-=-
Modified: bluebream/website/docs/v1.0/tutorial1.rst
===================================================================
--- bluebream/website/docs/v1.0/tutorial1.rst 2010-03-06 16:11:18 UTC (rev 109709)
+++ bluebream/website/docs/v1.0/tutorial1.rst 2010-03-06 18:05:42 UTC (rev 109710)
@@ -17,8 +17,8 @@
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
-collector application. This will help you to familiarize more
-concepts in BlueBream.
+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:
@@ -39,18 +39,19 @@
.. _tut1-new-project:
-Starting new project
---------------------
+Starting a new project
+----------------------
-Using project template
-~~~~~~~~~~~~~~~~~~~~~~
+Using the *bluebream* project template
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
In this section, we will create the directory layout for ticket
collector application. I assume you have already installed
-``bluebream`` using ``easy_install bluebream`` command as mentioned
-in the :ref:`started-getting`. We are going to use the project name
-as ``ticketcollector`` and namespace package as ``tc``. Let's create
-the project directory layout for ``ticketcollector``::
+``bluebream`` using the ``easy_install bluebream`` command as
+mentioned in the :ref:`started-getting` chapter. We are going to use
+the project name ``ticketcollector`` and namespace package name
+``tc``. Let's create the project directory layout for
+``ticketcollector``::
$ paster create -t bluebream
Selected and implied templates:
@@ -127,11 +128,11 @@
As you can see above, we have provided most of the project details.
Later, you can change the values provided here. However, changing
the package name or namespace package name may not be easy as
-changing the description. Because, the name and namespace package
-might be referred from many places.
+changing the description because the name and namespace package might
+be referred to from many places.
-Organize new package
-~~~~~~~~~~~~~~~~~~~~
+Organize the new package
+~~~~~~~~~~~~~~~~~~~~~~~~
If you change directory to ``ticketcollector``, you can see few
directories and files::
@@ -140,10 +141,10 @@
bootstrap.py debug.ini etc/ src/ var/
buildout.cfg deploy.ini setup.py templates/ versions.cfg
-Once the project directory layout is ready, you can add it to your
-version controlling system. You need **not** to add
-``src/ticketcollector.egg-info`` directory as it is generated by
-setuptools. Here is an example using `bzr
+Once the project directory layout is ready you can add it to your
+version control system. You **should not** add
+``src/ticketcollector.egg-info`` directory as it is generated
+automatically by setuptools. Here is an example using `bzr
<http://bazaar.canonical.com/en/>`_::
jack at computer:/projects/ticketcollector$ rm -fr src/ticketcollector.egg-info/
@@ -161,34 +162,33 @@
...
Committed revision 1.
-Adding source code to version controlling system is an optional step,
-but it is recommended even for experiments. Now you have, a ready to
-use, stand alone source code. You need not to have the ``bluebream``
-distribution installed anymore to function any task. The source code
-contains mechanism to install dependencies and setup other things
-required. The only necessary things you need to have is a pure
-Python installation and Internet access to PyPI. We will see how
-this is becoming possible in the upcoming sections.
+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.
+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.
-Buildout
-~~~~~~~~
+Bootstrapping the project
+~~~~~~~~~~~~~~~~~~~~~~~~~
-The next step is building the application using Buildout. The
-purpose of Buildout is to automate all the process involved in
-building any Python application/package from scratch. The only basic
-requirement for Buildout is a Python installation. Buildout provides
-a bootstrapping script to initialize Buildout. This bootstrap script
-named ``bootstrap.py`` will do these things:
+The next step is to install Buildout. The purpose of Buildout is to
+automate the building of Python applications from their bare source
+code form. The only basic requirement for Buildout is a Python
+installation. BlueBream provides a bootstrapping script to install
+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 ``setuptools`` package from PyPI
- Download and install ``zc.buildout`` package from PyPI
-- Create directory structure eg:- bin/ eggs/ parts/ develop-eggs/
+- Create a directory structure eg:- bin/ eggs/ parts/ develop-eggs/
-- Create a script inside ``bin`` directory named ``buildout``
+- Create a script inside the ``bin`` directory named ``buildout``
-When you run the ``bootstrap.py``, you can see that it creates few
+When you run ``bootstrap.py`` you can see that it creates a few
directories and the ``bin/buildout`` script as mentioned earlier::
jack at computer:/projects/ticketcollector$ python2.6 bootstrap.py
@@ -198,27 +198,27 @@
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 install all the executable
scripts.
-- The ``eggs`` directory is where buildout install Python eggs
+- The ``eggs`` directory is where Buildout install Python eggs
- The ``parts`` is where Buildout save all output generated by buildout.
Buildout expects you to not change anything inside parts directory
as it is auto generated by Buildout.
-- The ``develop-eggs`` directory is where buildout save links to all
- locally developing Python eggs.
+- The ``develop-eggs`` directory is where Buildout save links to all
+ locally developped Python eggs.
Buildout configuration
~~~~~~~~~~~~~~~~~~~~~~
-After bootstrapping the Buildout, you can perform the real building
-of your application. All the steps you did so far is not required to
-be repeated. But the build step will be repeated whenever you make
-changes to the buildout configuration. Now you are ready to run the
-``bin/buildout`` to build the application. Before running the
-buildout, let's see the content of ``buildout.cfg``::
+After bootstrapping the project you can build your application. All
+the steps you did so far is 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 the
+content of ``buildout.cfg``::
[config]
site_zcml = ${buildout:directory}/etc/site.zcml
@@ -255,12 +255,11 @@
called *parts*. The main part is called ``[buildout]``, and that is
given as the second part in the above configuration file. We have
added a part named ``[config]`` for convenience which includes some
-common options referred from other places. Each part will be handled
-by the Buildout plugin mechanism called recipes, with few exceptions.
-However, the main part ``[buildout]`` need not to have any recipe,
-this part will be handled by Buildout itself. As you can see above
-``[config]`` part also doesn't have any recipe. So, the ``[config]``
-part itself will not be performing any actions.
+common options referred to from other places. Each part will be
+handled by the Buildout plugin mechanism called recipes except for
+``[buildout]`` and ``[config]``. ``[buildout]`` is handled specially
+by Buildout as it contains general settings and ``[config]`` only
+contains options used for other parts.
We will look at each part here. Let's start with ``[config]``::
@@ -270,10 +269,9 @@
filestorage = ${buildout:directory}/var/filestorage
log = ${buildout:directory}/var/log
-The ``[config]`` is kind of meta part which is created for
-convenience to hold some common options used by other parts and
-templates. Using ``[config]`` part is a good Buildout pattern used
-by many users. In the above given configuration, the options
+The ``[config]`` is a kind of abstract part which exists for
+convenience to hold options used by other parts and is an idiom in
+many projects using Buildout. In this configuration the options
provided are _not_ used by other parts directly, but all are used in
one template given in the ``[zope_conf]`` part. Here is details
about each options:
@@ -300,26 +298,27 @@
zope_conf
test
-The second option ``develop`` says to buildout that, the current
-directory is a Python distribution source, i.e., there is a
-``setup.py`` file. Buildout will inspect the ``setup.py`` and add
-create develop egg link inside ``develop-eggs`` directory. The link
-file should contain path to location where the Python package is
-residing. So, buildout will make sure that the packages is always
-importable. The value of ``develop`` option could be a relative path
+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.
-The ``extends`` option says buildout to include the full content of
+The ``extends`` option tells buildout to include the full content of
``versions.cfg`` file as part the configuration. The
-``versions.cfg`` is another Buildout configuration file which
-contains the release numbers of different dependencies. You can add
-multiple lines to ``extends`` option to include multiple
-configuration files.
+``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
+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. So, you cannot
-include ``config`` part here as it doesn't have any recipe.
+Buildout expects a recipe for each parts listed here. Which means
+that you cannot include ``config`` part here as it doesn't have any
+recipe associated with it.
Now let's look at the ``app`` part::
@@ -337,21 +336,21 @@
<http://pypi.python.org/pypi/zc.recipe.egg>`_ is an advanced Buildout
recipe with many features to deal with egg. Majority 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 create
-by this part. The custom interpreter contains path to all eggs
-listed here.
+option ``eggs`` list all the eggs. The first egg, ``ticketcollector``
+is the main locally developing egg. The last option, ``interpreter``
+specify the name of a custom interpreter create by this part. The
+custom interpreter contains the paths to all eggs listed here.
-The ``zope_conf]`` part creates the ``zope.conf`` from a template::
+The ``[zope_conf]`` part creates the ``zope.conf`` from a template::
[zope_conf]
recipe = collective.recipe.template
input = templates/zope_conf.in
output = etc/zope.conf
-This part must be very self explanatory, it creates a ``zope.conf``
-file from one template file. This `collective.recipe.template recipe
+This part is fairly self explanatory, it creates a ``zope.conf`` file
+from the template file ``templates/zope_conf.in``. This
+`collective.recipe.template recipe
<http://pypi.python.org/pypi/collective.recipe.template>`_ is very
popular among Buildout users. Here is the template file
(``templates/zope_conf.in``)::
@@ -403,21 +402,21 @@
# production
devmode on
-The last part creates test runner::
+The last part creates the test runner::
[test]
recipe = zc.recipe.testrunner
eggs = ticketcollector
-The testrunner recipe creates 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.
-Running Buildout
-~~~~~~~~~~~~~~~~
+Building the project
+~~~~~~~~~~~~~~~~~~~~
-Now you can run the ``bin/buildout`` command. This will take some
-time to download packages from PyPI. When you run buildout, it will
+Now you can run the ``bin/buildout`` command. It will take some time
+to download all packages from PyPI. When you run buildout, it will
show something like this::
jack at computer:/projects/ticketcollector$ ./bin/buildout
@@ -447,7 +446,7 @@
-------------------
BlueBream use ZCML for application specific configuration. ZCML is
-an XML based declarative configuration language. As you have seen
+an XML-based declarative configuration language. As you have seen
already in ``zope.conf`` the main configuration is located at
``etc/site.zcml``. Here is the default listing::
@@ -496,10 +495,10 @@
The main configuration, ``site.zcml`` include other configuration
files specific to packages. The ZCML has some directives like
-`include``, ``page``, ``defaultView`` etc. available at various XML
-namespaces. In the ``site.zcml`` the default XML namespace is
+`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 namespace defined like this::
+site.zcml, you can see the XML-namespace refered to like this::
<configure
xmlns="http://namespaces.zope.org/zope">
@@ -623,7 +622,7 @@
""",
)
-Most of the details in the ``setup.py`` is what you given while
+Most of the details in the ``setup.py`` is what you're given when
creating the project from 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
@@ -639,7 +638,7 @@
``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
-cases, layers etc. BlueBream use `z3c.testsetup
+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
@@ -659,7 +658,7 @@
To run all test cases, use the ``bin/test`` command::
- jack at computer:/projects/ticketcollector$ ./bin/test
+ jack at computer:/projects/ticketcollector$ bin/test
This command will find all the test cases and run it.
@@ -747,7 +746,7 @@
>>> root['c1']
<tc.main.MyContainer object at 0x96091ac>
-Peristing any random objects like this is not a good idea. The next
+Persisting any random objects like this is not a good idea. The next
section will explain how to create a formal schema for your objects.
Now you can delete the object and remove ``MyContainer`` class
definition from ``src/tc/main/__init__.py``. You can delete the
More information about the checkins
mailing list