[Checkins] SVN: Sandbox/philikon/zopeproject/trunk/README.txt Rearrange tutorial a bit by introducing some top-level sections for grouping

[Philipp von Weitershausen]

Log message for revision 80387:
  Rearrange tutorial a bit by introducing some top-level sections for grouping
  
  Added pointers about how to rename or move a sandbox as well as archiving/sharing
  sandboxes
  
  Added credits
  

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

-=-
Modified: Sandbox/philikon/zopeproject/trunk/README.txt
===================================================================
--- Sandbox/philikon/zopeproject/trunk/README.txt	2007-09-29 13:37:51 UTC (rev 80386)
+++ Sandbox/philikon/zopeproject/trunk/README.txt	2007-09-29 13:59:21 UTC (rev 80387)
@@ -106,8 +106,8 @@
 ``~/.buildout/default.cfg``), the generated ``buildout.cfg`` will not
 contain a reference to path.
 
-Command line options
-====================
+Command line options for zopeproject
+====================================
 
 ``--no-buildout``
   When invoked with this option, ``zopeproject`` will only create the
@@ -137,8 +137,11 @@
   of ``easy_install`` (used to install ``zc.buildout``) and the
   ``buildout`` command.
 
+The sandbox
+===========
+
 What are the different files and directories for?
-=================================================
+-------------------------------------------------
 
 ``deploy.ini``
   Configuration file for PasteDeploy_.  It defines which server
@@ -198,8 +201,52 @@
   The ZODB filestorage will place its files (``Data.fs``, lock files,
   etc.) here.
 
+Renaming
+--------
+
+You can rename or move the sandbox directory any time you like.  Just
+be sure to run ``bin/buildout`` again after doing so.  Renaming the
+sandbox directory won't change the name of the egg, however. To do
+that, you'll have to change the ``name`` parameter in ``setup.py``.
+
+Sharing and archiving sandboxes
+-------------------------------
+
+You can easily share sandboxes with co-developers or archive them in a
+version control system such as subversion.  You can theoretically
+share or archive the whole sandbox directory, though it's recommended
+**not to include** the following files and directories because they
+can and will be generated by zc.buildout from the configuration files:
+
+* ``bin/``
+
+* ``parts/``
+
+* ``develop-eggs/``
+
+* all files in ``var/``
+
+* all files in ``log/``
+
+* ``.installed.cfg``
+
+If you receive a sandbox thas has been archived (e.g. by checking it
+out from a version control system), you will first have to bootstrap
+it in order to obtain the ``bin/buildout`` executable.  To do that,
+use the ``buildout`` script from any other sandbox on your machine::
+
+  $ .../path/to/some/sandbox/bin/buildout bootstrap
+
+Now the sandbox has its own ``bin/buildout`` script and can be
+installed::
+
+  $ bin/buildout
+
+Developing
+==========
+
 First steps with your application
-=================================
+---------------------------------
 
 After having started up Zope for the first time, you'll likely want to
 start developing your web application.  Code for your application goes
@@ -237,7 +284,7 @@
 visit http://localhost:8080/hello to see the page in action.
 
 Adding dependencies to the application
-======================================
+--------------------------------------
 
 The standard ``setup.py`` and ``configure.zcml`` files list a set of
 standard dependencies that are typical for most Zope applications.
@@ -262,7 +309,7 @@
   $ bin/buildout
 
 Writing and running tests
-=========================
+-------------------------
 
 Automated tests should be placed in Python modules.  If they all fit
 in one module, the module should simply be named ``tests``.  If you
@@ -290,8 +337,8 @@
 
   $ bin/test
 
-Writing functional tests
-------------------------
+Functional tests
+----------------
 
 While unit test typically require no or very little test setup,
 functional tests normally bootstrap the whole application's
@@ -381,7 +428,19 @@
 Questions can also be directed to the zope3-users mailinglist:
 http://mail.zope.org/mailman/listinfo/zope3-users
 
+Credits
+=======
 
+zopeproject is written and maintained by Philipp von Weitershausen.
+It was inspired by the similar grokproject tool from the same author.
+
+James Gardner, Martijn Faassen, Jan-Wijbrand Kolman and others gave
+valuable feedback on the early prototype presented at EuroPython 2007.
+
+Michael Bernstein gave valuable feedback and made many suggestions for
+improvements.
+
+
 .. _virtual-python: http://peak.telecommunity.com/DevCenter/EasyInstall#creating-a-virtual-python
 .. _workingenv: http://cheeseshop.python.org/pypi/workingenv.py
 .. _zc.buildout: http://cheeseshop.python.org/pypi/zc.buildout