[Checkins] SVN: Sandbox/philikon/zopeproject/trunk/ Improve README

Tue Jul 17 13:20:51 EDT 2007

Log message for revision 78080:
  Improve README
  

Changed:
  U   Sandbox/philikon/zopeproject/trunk/README.txt
  U   Sandbox/philikon/zopeproject/trunk/TODO.txt

-=-
Modified: Sandbox/philikon/zopeproject/trunk/README.txt
===================================================================

--- Sandbox/philikon/zopeproject/trunk/README.txt	2007-07-17 16:23:34 UTC (rev 78079)
+++ Sandbox/philikon/zopeproject/trunk/README.txt	2007-07-17 17:20:51 UTC (rev 78080)
@@ -1,21 +1,27 @@
-With ``zopeproject`` you can start a new Zope-based web application from
-scratch with just a two commands::
+``zopeproject`` provides tools and scripts for creating development
+sandboxes for web applications that primarily use Zope.
 
+Quickstart
+----------
+
+You can start a new Zope-based web application from scratch with just
+a two commands::
+
   $ easy_install zopeproject
   $ zopeproject MyZopeProj
 
-This will ask you for the name and password for an initial
-administrator user.  It will also ask you where to put the Python
-packages ("eggs") that it downloads.  This way multiple projects
-created with ``zopeproject`` can share the same packages and won't
-have to download them each time.
+The second command will ask you for the name and password for an
+initial administrator user.  It will also ask you where to put the
+Python packages ("eggs") that it downloads.  This way multiple
+projects created with ``zopeproject`` can share the same packages and
+won't have to download them each time.
 
 After asking the questions, ``zopeproject`` will download the
-``zc.buildout`` package that will be used to build the sandbox, unless
-``zc.buildout`` is already installed locally.  Then it will invoke
-``zc.buildout`` to download Zope and its dependecies.  If you're doing
-this for the first time or not sharing packages between different
-projects, this may take a while.
+`zc.buildout`_ package that will be used to build the sandbox, unless
+it is already installed locally.  Then it will invoke ``buildout`` to
+download Zope and its dependecies.  If you're doing this for the first
+time or not sharing packages between different projects, this may take
+a while.
 
 When ``zopeproject`` is done, you will find a typical Python package
 development environment in the ``MyZopeProj`` directory: the package
@@ -26,7 +32,107 @@
   $ cd MyZopeProj
   $ bin/paster serve deploy.ini
 
+After starting the application with ``paster``, you should now be able
+to go to http://localhost:8080 and see the default start screen of
+Zope.  You will also be able to log in with the administrator user
+account that you specified earlier.
 
+Command line options
+--------------------
+
+``--no-buildout``
+  When invoked with this option, ``zopeproject`` will only create the
+  project directory with the standard files in it, but it won't
+  download and invoke ``zc.buildout``.
+
+``--newer``
+  This option enables the ``newest = true`` setting in
+  ``buildout.cfg``.  That way, buildout will always check for newer
+  versions of eggs online.  If, for example, you have outdated
+  versions of your dependencies in your shared eggs directory, this
+  switch will force the download of newer versions.
+
+``--svn-repository=REPOS``
+  This option will import the project directory and the files in it
+  into the given subversion repository and provide you with a checkout
+  of the ``trunk``.  ``REPOS`` is supposed to be a repository path
+  that is going to be created, along with ``tags``, ``branches`` and
+  ``trunk`` below that.
+
+``-v``, ``--verbose``
+  When this option is enabled, ``zopeproject`` won't hide the output
+  of ``easy_install`` (used to install ``zc.buildout``) and the
+  ``buildout`` command.
+
+What are the different files for?
+---------------------------------
+
+``deploy.ini``
+  Configuration file for PasteDeploy_.  It defines which server
+  software to launch and which WSGI application to invoke upon each
+  request (which is defined in ``myzopeproj/application.py``).  You
+  may also define WSGI middlewares here.  Invoke ``bin/paster serve``
+  with this file as an argument.
+
+``zope.conf``
+  This file will be read by the application factory in
+  ``myzopeproj/application.py``.  Here you can define which ZCML file
+  the application factory should load upon startup, the ZODB database
+  instance, an event log as well as whether developer mode is switched
+  on or not.
+
+``site.zcml``
+  This file is referred to by ``zope.conf`` and will be loaded by the
+  application factory.  It is the root ZCML file and includes
+  everything else that needs to be loaded.  That typically is just the
+  application package itself, ``myzopeproj``, which then goes on to
+  include its dependencies.  Apart from this, ``site.zcml`` also
+  defines the anonymous principal and the initial admin principal.
+
+``setup.py``
+  This file defines the egg of your application.  That includes the
+  package's dependencies (mostly Zope eggs) and the entry point for
+  the PasteDeploy_ application factory.
+
+``buildout.cfg``
+  This file tells `zc.buildout`_ what to do when the buildout is
+  executed.  This mostly involves executing ``setup.py`` to enable the
+  ``MyZopeProj`` egg (which also includes downloading its
+  dependencies), as well as installing PasteDeploy_ for the server.
+  This files also refers to the shared eggs directory
+  (``eggs-directory``) and determines whether buildout should check
+  whether newer eggs are available online or not (``newest``).
+
+Adding dependencies to the application
+--------------------------------------
+
+The standard ``setup.py`` and ``configure.zcml`` files list a set of
+standard dependencies that is typical for most Zope applications.  You
+may obviously remove things from this list, but typically you'll want
+to re-use libraries that others have written.  Many, if not most, of
+additional Zope and third party libraries are `listed on the Python
+Cheeseshop`_.
+
+Let's say you wanted to reuse the ``some.library`` package in your
+application.  The first step would be to add it to the list of
+dependencies in ``setup.py`` (``install_requires``).  If this package
+defined any Zope components, you would probably also have to load its
+ZCML configuration by adding the following line to
+``myzopeproj/configure.zcml``::
+
+  <include package="some.library" />
+
+After having changed ``setup.py``, you would want the newly added
+dependency to be downloaded and added to the search path of
+``bin/paster``.  To do that, simply invoke the buildout::
+
+  $ bin/buildout
+
+.. _zc.buildout: http://cheeseshop.python.org/pypi/zc.buildout
+.. _PasteDeploy: http://pythonpaste.org/deploy/
+.. _listed on the Python Cheeseshop: http://cheeseshop.python.org/pypi?:action=browse&c=515
+
+
 Changes
 =======
 
@@ -37,6 +143,8 @@
   ~/.buildout/default.cfg, it is used as the default value for the
   eggs directory.
 
+* Greatly improved the README.txt file.
+
 0.3.1 (2007-07-15)
 ------------------
 

Modified: Sandbox/philikon/zopeproject/trunk/TODO.txt
===================================================================
--- Sandbox/philikon/zopeproject/trunk/TODO.txt	2007-07-17 16:23:34 UTC (rev 78079)
+++ Sandbox/philikon/zopeproject/trunk/TODO.txt	2007-07-17 17:20:51 UTC (rev 78080)
@@ -5,18 +5,9 @@
 * Allow values to be provided thru command line arguments
   See https://bugs.launchpad.net/grok/+bug/125817.
 
-* README: explain what site.zcml, zope.conf are.
-
-* README: explain how to add more dependencies to your new
-  application.
-
-* README: document different command line options, e.g. --newest for
-  checking for newer eggs.
-
 * Maybe rename application.py to app_factory.py or something like
   that? (application.py sort of collides with grok's app.py)
 
-* Discover existing egg cache settings and use those as defaults:
-  https://bugs.launchpad.net/grok/+bug/125817
+* ftesting.zcml and testing.py
 
 * Need tests!

