[Checkins] SVN: bluebream/website/docs/v1.0/gettingstarted.rst - cleanup

Baiju M baiju.m.mail at gmail.com
Wed Apr 28 06:42:44 EDT 2010


Log message for revision 111539:
  - cleanup
  - M-q
  

Changed:
  U   bluebream/website/docs/v1.0/gettingstarted.rst

-=-
Modified: bluebream/website/docs/v1.0/gettingstarted.rst
===================================================================
--- bluebream/website/docs/v1.0/gettingstarted.rst	2010-04-28 10:25:23 UTC (rev 111538)
+++ bluebream/website/docs/v1.0/gettingstarted.rst	2010-04-28 10:42:44 UTC (rev 111539)
@@ -32,21 +32,21 @@
 Before proceeding further, let's have an overview of the sections.
 
 - **Preparations:** -- This section discusses about the prerequisites
-  and preparations the user needs to start a web application project using
-  BlueBream.
+  and preparations the user needs to start a web application project
+  using BlueBream.
 
 - **Installation:** -- It gives the user instructions for installing
   BlueBream.
 
 - **Creating a sample project:** -- This section explains the user
-  how to create a sample web application project using the ``bluebream``
-  project template.
+  how to create a sample web application project using the
+  ``bluebream`` project template.
 
-- **Building the application:** -- This section explains the user how to
-  build the application using Buildout.
+- **Building the application:** -- This section explains the user how
+  to build the application using Buildout.
 
-- **Basic usage:** -- This section explains the basic usage of
-  the BlueBream commands.
+- **Basic usage:** -- This section explains the basic usage of the
+  BlueBream commands.
 
 - **Package directory structure:** -- This section shows the
   directory structure and describes the purpose of each directory and
@@ -60,35 +60,38 @@
 Requirements
 ------------
 
-This document assumes that user has already installed Python_ 2.4, 2.5 or 2.6
-and Distribute_ (or Setuptools_).  If Distribute (or Setuptools) is installed,
-the user will get an ``easy_install`` command which can be used to install the
-``bluebream`` distribution.  Another way of installing ``bluebream`` is by using
-`PIP`_, a replacement for ``easy_install`` which is meant to improve on it.
+This document assumes that user has already installed Python_ 2.4,
+2.5 or 2.6 and Distribute_ (or Setuptools_).  If Distribute (or
+Setuptools) is installed, the user will get an ``easy_install``
+command which can be used to install the ``bluebream`` distribution.
+Another way of installing ``bluebream`` is by using `PIP`_, a
+replacement for ``easy_install`` which is meant to improve on it.
 Among advantages, you will be able to uninstall packages.
 
-The user can also install BlueBream inside an isolated Python environment
-created using `Virtualenv`_.  Although, *virtualenv* is not required when
-working on the application itself, because `Buildout`_ is available by default
-in the application created.  Buildout is the recommended approach to create
-repeatable, isolated working environments.  Buildout is a declarative,
+The user can also install BlueBream inside an isolated Python
+environment created using `Virtualenv`_.  Although, *virtualenv* is
+not required when working on the application itself, because
+`Buildout`_ is available by default in the application created.
+Buildout is the recommended approach to create repeatable, isolated
+working environments.  Buildout is a declarative,
 configuration-driven build system created by Jim Fulton.
 
-It is recommended to use a custom-built Python for working with BlueBream. The
-user is required to install a C compiler (gcc) in his system, and to have
-internet access to PyPI_ to perform installation
-of the ``bluebream`` distribution, to bootstrap the buildout, and to build the
-application using Buildout. Internet access is not required for deployment if
-`zc.sourcerelease <http://pypi.python.org/pypi/zc.sourcerelease>`_ package is
-used.
+It is recommended to use a custom-built Python for working with
+BlueBream. The user is required to install a C compiler (gcc) in his
+system, and to have internet access to PyPI_ to perform installation
+of the ``bluebream`` distribution, to bootstrap the buildout, and to
+build the application using Buildout. Internet access is not required
+for deployment if `zc.sourcerelease
+<http://pypi.python.org/pypi/zc.sourcerelease>`_ package is used.
 
 .. _started-installation:
 
 Installation
 ------------
 
-If the user has installed Distribute_ (or Setuptools_), an ``easy_install``
-command will be available and can be used to install BlueBream.
+If the user has installed Distribute_ (or Setuptools_), an
+``easy_install`` command will be available and can be used to install
+BlueBream.
 
 ::
 
@@ -98,61 +101,64 @@
 
   $ sudo easy_install bluebream
 
-Try to avoid running "easy_install" commands as ``root`` or with ``sudo`` for
-larger installation because it can lead to conflicts with the packaging system
-of your OS. Installing the bluebream template like this is ok, because it does
-not pull a lot of dependencies.)
+Try to avoid running "easy_install" commands as ``root`` or with
+``sudo`` for larger installation because it can lead to conflicts
+with the packaging system of your OS. Installing the bluebream
+template like this is ok, because it does not pull a lot of
+dependencies.
 
-As mentioned earlier, Internet access to PyPI_ is required to perform installation
-of the ``bluebream`` distribution.  If the user is behind a proxy, it's up to
-him to make sure it works.  The ``easy_install`` will look for
-the environment variable named ``http_proxy`` on a GNU/Linux platforms.
-The user can set it like this::
+As mentioned earlier, Internet access to PyPI_ is required to perform
+installation of the ``bluebream`` distribution.  If the user is
+behind a proxy, it's up to him to make sure it works.  The
+``easy_install`` will look for the environment variable named
+``http_proxy`` on a GNU/Linux platforms.  The user can set it like
+this::
 
  $ export http_proxy="http://username:password@PROXY-IP-ADDRESS:PORT"
 
-Apart from the ``bluebream`` distribution, easy_install will download and
-install a few dependencies.  The dependencies are:
+Apart from the ``bluebream`` distribution, easy_install will download
+and install a few dependencies.  The dependencies are:
 
 - PasteScript_
 - PasteDeploy_
 - Paste_
 
-Installing the ``bluebream`` template package is a one time process.  Once the
-project package is ready, the user does not need the ``bluebream`` template
-package anymore because the package user is about to create will be
-self-bootstrappable.
+Installing the ``bluebream`` template package is a one time process.
+Once the project package is ready, the user does not need the
+``bluebream`` template package anymore because the package user is
+about to create will be self-bootstrappable.
 
 .. _started-sample-project:
 
 Creating a sample project
 -------------------------
 
-The ``bluebream`` distribution provides a project template based on PasteScript_
-templates.  Once BlueBream is installed, run the ``paster`` command to create
-the project directory structure.  The ``create`` sub-command provided by
-``paster`` will show a command-line wizard to create the project directory
-structure.
+The ``bluebream`` distribution provides a project template based on
+PasteScript_ templates.  Once BlueBream is installed, run the
+``paster`` command to create the project directory structure.  The
+``create`` sub-command provided by ``paster`` will show a
+command-line wizard to create the project directory structure.
 
 ::
 
   $ paster create -t bluebream
 
-This will bring a wizard asking details about the new project.  The user can
-choose the package name and version number in the wizard itself. These details
-can also be modified later.  Now, the user gets a working application with the
-project name as the name of the egg. The project name can be a dotted name, if
-the user wants his project to be part of a namespace. Any number of namespace
-levels can be used. The project can be called 'sample', 'sample.main' or
-'sample.app.main' or anything deeper if necessary. The subfolder structure will
-be created accordingly.
+This will bring a wizard asking details about the new project.  The
+user can choose the package name and version number in the wizard
+itself. These details can also be modified later.  Now, the user gets
+a working application with the project name as the name of the
+egg. The project name can be a dotted name, if the user wants his
+project to be part of a namespace. Any number of namespace levels can
+be used. The project can be called 'sample', 'sample.main' or
+'sample.app.main' or anything deeper if necessary. The subfolder
+structure will be created accordingly.
 
 Here is a screenshot of sample project creation:
 
 .. image:: images/gettingstarted1.png
 
-The project name and other parameters can be given as a
-command line argument::
+The project name and other parameters can be given as a command line
+argument::
 
   $ paster create -t bluebream sampleproject
 
@@ -198,23 +204,24 @@
 Building the application
 ------------------------
 
-As mentioned earlier, the generated package is bundled with a Buildout
-configuration (``buildout.cfg``) and a bootstrap script
+As mentioned earlier, the generated package is bundled with a
+Buildout configuration (``buildout.cfg``) and a bootstrap script
 (``bootstrap.py``).  First, the user needs to bootstrap the buildout
 itself::
 
   $ cd sampleproject
   $ python bootstrap.py
 
-The bootstrap script will download and install the ``zc.buildout`` and
-``distribute`` packages.  Also, it will create the basic directory structure.
+The bootstrap script will download and install the ``zc.buildout``
+and ``distribute`` packages.  Also, it will create the basic
+directory structure.
 
 Here is a screenshot of bootstrapping the buildout:
 
 .. image:: images/gettingstarted2.png
 
-The next step is building the application.  To build the application, run
-the buildout::
+The next step is building the application.  To build the application,
+run the buildout::
 
   $ ./bin/buildout
 
@@ -222,20 +229,28 @@
 
 .. image:: images/gettingstarted3.png
 
-The buildout script will download all dependencies and setup the environment to
-run your application. This can take some time because many packages are
-downloaded. If you don't want these packages to be downloaded again the next
-time you create a project, you can set a shared directory in your personal
-buildout configuration: create a file ``~/.buildout/default.cfg`` (and the .buildout
-folder if needed), with the following contents (replace 'user' with the real
-username)::
+The buildout script will download all dependencies and setup the
+environment to run your application. This can take some time because
+many packages are downloaded. If you don't want these packages to be
+downloaded again the next time you create a project, you can set a
+shared directory in your personal buildout configuration: create a
+file ``~/.buildout/default.cfg`` (and the .buildout folder if
+needed), with the following contents::
 
     [buildout]
-    eggs-directory = /home/user/buildout-eggs
+    newest = false
+    unzip = true
+    download-cache = /opt/buildout-download-cache
 
-You can choose any value for the eggs-directory, buildout will create it for
-you.
+You can choose any value for the ``download-cache``, buildout will
+create it for you.
 
+If you set the ``newest = false`` option, buildout will not look for
+new version of packages in package server by default.  The ``unzip =
+true`` makes Buildout to unzip all eggs irrespective of whether it is
+Zip safe or not.  The ``download-cache`` is the directory where
+Buildoout keeps a cached copy the source eggs downloaded.
+
 The next section will show the basic usage.
 
 .. _started-basic-usage:
@@ -244,27 +259,28 @@
 -----------
 
 The most common thing a user needs while developing an application is
-running the server.  BlueBream uses the ``paster`` command provided by
-PasteScript to run the WSGI server.  To run the server, the user can pass
-the PasteDeploy configuration file as the argument to the ``serve``
-sub-command as given here::
+running the server.  BlueBream uses the ``paster`` command provided
+by PasteScript to run the WSGI server.  To run the server, the user
+can pass the PasteDeploy configuration file as the argument to the
+``serve`` sub-command as given here::
 
   $ ./bin/paster serve debug.ini
 
-After starting the server, the user can access the site from his browser on
-this URL: http://localhost:8080/ .  The port number (``8080``) can be
-changed in PasteDeploy configuration file (``debug.ini``) to user
-choice.
+After starting the server, the user can access the site from his
+browser on this URL: http://localhost:8080/ .  The port number
+(``8080``) can be changed in PasteDeploy configuration file
+(``debug.ini``) to user choice.
 
 When the user opens the browser, it will look like as shown in this
 screenshot:
 
 .. image:: images/gettingstarted4.png
 
-The second most common thing that should be run are the unit tests.  BlueBream
-creates a testrunner using the ``zc.recipe.testrunner`` Buildout recipe. The user
-can see a ``test`` command inside the ``bin`` directory.  To run the test cases,
-the following command is used::
+The second most common thing that should be run are the unit tests.
+BlueBream creates a testrunner using the ``zc.recipe.testrunner``
+Buildout recipe. The user can see a ``test`` command inside the
+``bin`` directory.  To run the test cases, the following command is
+used::
 
   $ ./bin/test
 
@@ -291,7 +307,9 @@
     |-- debug.ini
     |-- deploy.ini
     |-- etc
-    |   `-- site.zcml
+    |   |-- site.zcml
+    |   |-- zope.conf
+    |   `-- zope-debug.conf
     |-- setup.py
     |-- src
     |   |-- myproject
@@ -323,8 +341,6 @@
     |       |-- not-zip-safe
     |       |-- requires.txt
     |       `-- top_level.txt
-    |-- templates
-    |   `-- zope_conf.in
     |-- var
     |   |-- filestorage
     |   |   `-- README.txt
@@ -353,9 +369,12 @@
 
 - ``etc/site.zcml`` -- The toplevel ZCML file (from which all others are loaded)
 
-- ``etc/zope.conf`` -- The main Zope and ZODB configuration file (generated
-  from the template)
+- ``etc/zope.conf`` -- The main Zope and ZODB configuration file
+  (Used by ``deploy.ini``)
 
+- ``etc/zope-debug.conf`` -- The main Zope and ZODB configuration
+  file (Used by ``debug.ini``)
+
 - ``setup.py`` -- Project meta-data to create a distributable archive (a
   distribution)
 
@@ -395,12 +414,6 @@
 
 - ``src/myproject/welcome/`` -- A sample application.
 
-- ``templates/`` -- Buildout specific templates used by
-  "collective.recipe.template"
-
-- ``templates/zope_conf.in`` -- Zope conf template, modify this file
-  for any change in zope.conf
-
 - ``var/`` -- A place holder directory for storing all database files,
   log files etc.
 
@@ -423,16 +436,17 @@
 
 To create a web page which displays ``Hello World!``, you need to
 create a view class and register it using the ``browser:page`` ZCML
-directive.  In BlueBream, this is called a *Browser Page*.
-Sometimes more generic term, *Browser View* is used instead of *Browser Page*
+directive.  In BlueBream, this is called a *Browser Page*.  Sometimes
+more generic term, *Browser View* is used instead of *Browser Page*
 which can be used to refer to HTTP, XMLRPC, REST and other views.  By
 default, the page which you are getting when you access:
 http://localhost:8080 is a page registered like this.  You can see
-the registration inside ``configure.zcml``, the name of the view will be
-``index``.  You can access the default page by explicitly mentioning
-the page name in the URL like this: http://localhost:8080/@@index.
-You can refer the :ref:`howto-default-view` HOWTO for more details
-about how the default view for a container object is working.
+the registration inside ``configure.zcml``, the name of the view will
+be ``index``.  You can access the default page by explicitly
+mentioning the page name in the URL like this:
+http://localhost:8080/@@index.  You can refer the
+:ref:`howto-default-view` HOWTO for more details about how the
+default view for a container object is working.
 
 First you need to create a Python file named ``myhello.py`` at
 ``src/myproject/myhello.py``::



More information about the checkins mailing list