[Checkins] SVN: Zope/branches/2.12/doc/ Merge 'tseaver-clarify_install_docs' branch.

Tres Seaver tseaver at palladion.com
Mon Mar 8 17:54:01 EST 2010


Log message for revision 109858:
  Merge 'tseaver-clarify_install_docs' branch.

Changed:
  A   Zope/branches/2.12/doc/INSTALL-buildout.rst
  U   Zope/branches/2.12/doc/INSTALL.rst
  U   Zope/branches/2.12/doc/index.rst
  A   Zope/branches/2.12/doc/operation.rst

-=-
Copied: Zope/branches/2.12/doc/INSTALL-buildout.rst (from rev 109567, Zope/branches/tseaver-clarify_install_docs/doc/INSTALL-buildout.rst)
===================================================================
--- Zope/branches/2.12/doc/INSTALL-buildout.rst	                        (rev 0)
+++ Zope/branches/2.12/doc/INSTALL-buildout.rst	2010-03-08 22:54:01 UTC (rev 109858)
@@ -0,0 +1,181 @@
+Installing and Zope with ``zc.buildout``
+========================================
+
+.. highlight:: bash
+
+This document descibes how to get going with Zope using ``zc.buildout``.
+
+
+About ``zc.buildout``
+---------------------
+
+`zc.buildout <http://www.buildout.org/>`_ is a powerful tool for creating
+repeatable builds of a given software configuration and environment.  The
+Zope developers use ``zc.buildout`` to develop Zope itself, as well as
+the underlying packages it uses.
+
+Prerequisites
+-------------
+
+In order to use Zope, you must have the following pre-requisites
+available: 
+
+- A supported version of Python, including the development support if
+  installed from system-level packages.  Supported versions include:
+
+  * 2.6.x
+
+- Zope needs the Python ``zlib`` module to be importable.  If you are
+  building your own Python from source, please be sure that you have the
+  headers installed which correspond to your system's ``zlib``.
+
+- A C compiler capable of building extension modules for your Python
+  (gcc recommended). This is not necessary for Windows as binary
+  releases of the parts that would need compiling are always made
+  available.
+
+- If you wish to install Zope as a Service on Windows, you will need
+  to have the `pywin32`__ package installed.
+
+  __ https://sourceforge.net/projects/pywin32/
+
+
+Installing standalone Zope using zc.buildout
+--------------------------------------------
+
+In this configuration, we use ``zc.buildout`` to install the Zope software,
+but then generate server "instances" outside the buildout environment.
+
+Installing the Zope software
+::::::::::::::::::::::::::::
+
+Installing the Zope software using ``zc.buildout`` involves the following
+steps:
+
+- Download the Zope 2 source distribution from `PyPI`__
+
+  __ http://pypi.python.org/pypi/Zope2
+
+- Bootstrap the buildout
+
+- Run the buildout
+
+On Linux, this can be done as follows::
+
+  $ wget http://pypi.python.org/packages/source/Z/Zope2/Zope2-<Zope version>.tar.gz
+  $ tar xfvz Zope2-<Zope version>.tar.gz
+  $ cd Zope2-<Zope version>
+  $ /path/to/your/python bootstrap/bootstrap.py
+  $ bin/buildout
+
+
+Creating a Zope instance
+::::::::::::::::::::::::
+
+Once you've installed Zope, you will need to create an "instance
+home". This is a directory that contains configuration and data for a
+Zope server process.  The instance home is created using the
+``mkzopeinstance`` script::
+
+  $ bin/mkzopeinstance
+
+You can specify the Python interpreter to use for the instance
+explicitly:: 
+
+  $ bin/mkzopeinstance --python=$PWD/bin/zopepy
+
+You will be asked to provide a user name and password for an
+administrator's account during ``mkzopeinstance``.  To see the available
+command-line options, run the script with the ``--help`` option::
+
+  $ bin/mkzopeinstance --help
+
+.. note::
+  The traditional "inplace" build is no longer supported. If using
+  ``mkzopeinstance``, always do so outside the buildout environment.
+
+
+Creating a buildout-based Zope instance
+---------------------------------------
+
+Rather than installing Zope separately from your instance, you may wish
+to use ``zc.buildout`` to create a self-contained environment, containing
+both the Zope software and the configuration and data for your server.
+This procedure involves the following steps:
+
+- Create the home directory for the buildout, including 
+  ``etc``, ``logs`` and ``var`` subdirectories.
+
+- Fetch the buildout bootstrap script into the environment.
+
+- Create a buildout configuration as follows:
+
+.. topic:: buildout.cfg
+ :class: file
+
+ ::
+
+   [buildout]
+   parts = instance 
+   extends = http://download.zope.org/Zope2/index/<Zope version>/versions.cfg
+
+   [instance]
+   recipe = zc.recipe.egg
+   eggs = Zope2
+   interpreter = py
+   scripts = runzope zopectl
+   initialization =
+     import sys
+     sys.argv[1:1] = ['-C',r'${buildout:directory}/etc/zope.conf']
+
+This is the minimum but all the usual buildout techniques can be
+used.
+
+- Bootstrap the buildout
+
+- Run the buildout
+
+- Create a Zope configuration file.  A minimal version would be:
+
+.. topic:: etc/zope.cfg
+ :class: file
+
+ ::
+
+   %define INSTANCE <path to your instance directory>
+
+   python $INSTANCE/bin/py[.exe on Windows]
+ 
+   instancehome $INSTANCE
+
+A fully-annotated sample can be found in the Zope2 egg::
+
+   $ cat eggs/Zope2--*/Zope2/utilities/skel/etc/zope.conf.in
+
+.. highlight:: bash
+
+An example session::
+
+   $ mkdir /path/to/instance
+   $ cd /path/to/instance
+   $ mkdir etc logs var
+   $ wget http://svn.zope.org/zc.buildout/trunk/bootstrap/bootstrap.py
+   $ vi buildout.cfg
+   $ /path/to/your/python bootstrap.py
+   $ bin/buildout
+   $ cat eggs/Zope2--*/Zope2/utilities/skel/etc/zope.conf.in > etc/zope.conf
+   $ vi etc/zope.conf  # replace <<INSTANCE_HOME>> with buildout directory
+   $ bin/zopectl start
+
+In the ``bin`` subdirectory of your instance directory, you will
+find ``runzope`` and ``zopectl`` scripts that can be used as
+normal.
+
+You can use ``zopectl`` interactively as a command shell by just
+calling it without any arguments. Try ``help`` there and ``help <command>``
+to find out about additionally commands of zopectl. These commands
+also work at the command line.
+
+
+After installation, refer to :doc:`operation` for documentation on
+configuring and running Zope.

Modified: Zope/branches/2.12/doc/INSTALL.rst
===================================================================
--- Zope/branches/2.12/doc/INSTALL.rst	2010-03-08 22:49:05 UTC (rev 109857)
+++ Zope/branches/2.12/doc/INSTALL.rst	2010-03-08 22:54:01 UTC (rev 109858)
@@ -1,13 +1,13 @@
-============================
-Building and Installing Zope
-============================
+Installing Zope
+===============
 
 .. highlight:: bash
 
 This document descibes how to get going with Zope.
 
+
 Prerequisites
-=============
+-------------
 
 In order to use Zope, you must have the following pre-requisites
 available: 
@@ -31,82 +31,33 @@
 
   __ https://sourceforge.net/projects/pywin32/
 
+
 Installing Zope
-===============
+---------------
 
-Unless using buildout to build a zope instance as described
-:ref:`below <buildout-instances>`, you will need to install Zope
-separately. If you want to create a buildout-based Zope instance,
-please skip directly to that section.
+The recommended way to install Zope is within a virtualized Python environment
+using ``virtualenv`` as follows::
 
-Installing Zope using virtualenv
---------------------------------
-
-Zope can be installed within a virtualized Python environment using 
-``virtualenv`` as follows::
-
   $ virtualenv --no-site-packages my_zope
   $ cd my_zope
-  $ source bin/activate
   $ bin/easy_install -i http://download.zope.org/Zope2/index/<Zope version> Zope2
 
-Using ``virtualenv`` is **highly recommended**. Otherwise, you may encounter
-unexpected conflicts with packages that have already been installed.
+If you don't already have ``virtualenv`` installed on your system, download
+the latest release from the `virtualenv PyPI page
+<http://pypi.python.org/pypi/virtaulenv>`_, unpack it, and install it, e.g.::
 
-Once you've installed Zope, you'll need to :ref:`create an instance <classic-instances>`.
+  $ wget http://pypi.python.org/packages/source/v/virtualenv/virtualenv-1.4.5.tar.gz
+  $ tar xzf virtualenv-1.4.5.tar.gz
+  $ cd virtuaenv-1.4.5
+  $ /path/to/python2.6 setup.py install
 
-Installing Zope using zc.buildout
----------------------------------
+If you wish to manage your Zope instance using
+buildout, please see the :doc:`INSTALL-buildout`.
 
-Unless you are `developing zope`__, you most likely
-want to be creating a :ref:`buildout-based Zope instance <buildout-instances>` rather
-that installing using buildout as described in this section.
 
-__ http://docs.zope.org/developer/
+Creating a Zope Instance
+------------------------
 
-However, if you really just want to create Zope instances using the
-classic ``mkzopeinstance`` but with the software installed by buildout,
-then you need to do the following:
-
-- Download the Zope 2 source distribution from `PyPI`__
-
-  __ http://pypi.python.org/pypi/Zope2
-
-- Bootstrap the buildout
-
-- Run the buildout
-
-On Linux, this can be done as follows::
-
-  $ wget http://pypi.python.org/packages/source/Z/Zope2/Zope2-<Zope version>.tar.gz
-  $ tar xfvz Zope2-2.12.0.tar.gz
-  $ cd Zope2-2.12.0
-  $ /path/to/your/python bootstrap/bootstrap.py
-  $ bin/buildout
-
-Once you've installed Zope, you'll need to :ref:`create an instance <classic-instances>`.
-
-Installing Zope using easy_install
-----------------------------------
-
-Zope can be installed using ``easy_install``, but it is recommended to
-use ``virtualenv`` as described above to avoid unexpected conflicts
-with other packages installed directly in your python installation.
-
-However, if you want to use easy_install globally, all you need to do
-is::
-
-  $ easy_install -i http://download.zope.org/Zope2/index/<Zope version> Zope2
-
-This will create the related scripts such as ``mkzopeinstance`` within the
-scripts folder of your python installation. You can then use them to
-create instances as described below.
-
-.. _classic-instances:
-
-Creating a classic Zope Instance
-================================
-
 Once you've installed Zope, you will need to create an "instance
 home". This is a directory that contains configuration and data for a
 Zope server process.  The instance home is created using the
@@ -114,11 +65,6 @@
 
   $ bin/mkzopeinstance
 
-You can specify the Python interpreter to use for the instance
-explicitly:: 
-
-  $ bin/mkzopeinstance --python=$PWD/bin/zopepy
-
 You will be asked to provide a user name and password for an
 administrator's account during ``mkzopeinstance``.  To see the available
 command-line options, run the script with the ``--help`` option::
@@ -126,225 +72,9 @@
   $ bin/mkzopeinstance --help
 
 .. note::
-  The traditional "inplace" build is no longer supported. If using
-  ``mkzopeinstance``, always do so outside the buildout/virtualenv
-  environment. If you wish to manage your Zope instance using
-  buildout, please see the section below.
+  The traditional "inplace" build is no longer supported.  Always use
+  ``mkzopeinstance`` to create instances outside the virtualenv environment.
 
-.. _buildout-instances:
 
-Creating a buildout-based Zope Instance
-=======================================
-
-If you wish to use buildout to manage your Zope instance, then the
-instance is created as follows:
-
-* Create a directory for your instance. In this directory, create a
-  ``etc``, ``logs`` and ``var`` subdirectories.
-
-* Download the following file into your instance directory:
-
-  `http://svn.zope.org/*checkout*/zc.buildout/trunk/bootstrap/bootstrap.py`__
-    
-  __ http://svn.zope.org/*checkout*/zc.buildout/trunk/bootstrap/bootstrap.py
-
-.. highlight:: none
-
-* Create a buildout configuration as follows:
-
-.. topic:: buildout.cfg
- :class: file
-
- ::
-
-   [buildout]
-   parts = instance 
-   extends = http://download.zope.org/Zope2/index/<Zope version>/versions.cfg
-
-   [instance]
-   recipe = zc.recipe.egg
-   eggs = Zope2
-   interpreter = py
-   scripts = runzope zopectl
-   initialization =
-     import sys
-     sys.argv[1:1] = ['-C',r'${buildout:directory}/etc/zope.conf']
-
-This is the minimum but all the usual buildout techniques can be
-used.
-
-* Create a Zope configuration file starting as follows:
-
-.. topic:: etc/zope.cfg
- :class: file
-
- ::
-
-   %define INSTANCE <path to your instance directory>
-
-   python $INSTANCE/bin/py[.exe on Windows]
- 
-   instancehome $INSTANCE
-
-.. highlight:: bash
-
-* Now, run the following commands::
-
-    $ /path/to/your/python bootstrap.py
-    $ bin/buildout
-
-  In the ``bin`` subdirectory of your instance directory, you will
-  find ``runzope`` and ``zopectl`` scripts that can be used as
-  normal.
-
-Using your Zope instance
-========================
-
-There are various ways to run Zope from your newly created
-instance. They are all described below.
-
-Running Zope in the Foreground
-------------------------------
-
-To run Zope without detaching from the console, use the ``fg``
-command (short for ``foreground``)::
-
-  $ /path/to/zope/instance/bin/zopectl fg
-
-In this mode, Zope emits its log messages to the console, and does not
-detach from terminal.
-
-
-Running Zope as a Daemon
--------------------------
-
-Once an instance home has been created, the Zope server can now be
-started using this command::
-
-  $ /path/to/zope/instance/bin/zopectl start
-
-During start, zope emits log messages into ./log/event.log
-You can examine it with the usual tools (cat, more, tail)
-and see if there are any errors preventing zope from starting.
-
-.. highlight:: none
-.. note::
-
-  For this to work on Windows, the Zope instance must be installed as
-  a Service. This is done with::
-
-    bin\zopectl install
-
-  If you later want to remove this Service, do the following::
-
-    bin\zopectl remove
-
-  For the full list of options available for setting up Zope as a
-  Windows Service, do::
-
-    bin\zopectl install --help
-
-.. highlight:: bash
-
-Integrating with System Startup
--------------------------------
-
-zopectl can be linked as rc-script in the usual start directories
-on linux or other System V unix variants.
-
-You can use ``zopectl`` interactively as a command shell by just
-calling it without any arguments. Try ``help`` there and ``help <command>``
-to find out about additionally commands of zopectl. These commands
-also work at the command line.
-
-.. note::
-
-  On Windows, a Service can be installed and set to start
-  automatically with the following:
-
-  .. code-block:: none
-
-    bin\zopectl install --startup=auto
-
-Configuring Zope
-================
-
-Your Zope instance is configured through a file, either found by
-default::
-
-  $ /path/to/zope/instance/bin/zopectl show
-  ...
-  Config file:  /path/to/zope/instance/etc/zope.conf
-
-or passed explicitly on the commandline::
-
-  $ /path/to/zope/instance/bin/zopectl -c /tmp/other.conf show
-  ...
-  Config file:  /tmp/other.conf
-
-When starting Zope, if you see errors indicating that an address is in
-use, then you may have to change the ports Zope uses for HTTP or FTP. 
-The default HTTP and FTP ports used by Zope are
-8080 and 8021 respectively. You can change the ports used by
-editing ./etc/zope.conf appropriately.
-
-The section in the configuration file looks like this::
-
-  <http-server>
-    # valid keys are "address" and "force-connection-close"
-    address 8080
-    # force-connection-close on
-  </http-server>
-
-The address can just be a port number as shown, or a  host:port
-pair to bind only to a specific interface.
-
-Logging In To Zope
-==================
-
-Once you've started Zope, you can then connect to the Zope webserver
-by directing your browser to::
-
-  http://yourhost:8080/manage
-
-where 'yourhost' is the DNS name or IP address of the machine
-running Zope.  If you changed the HTTP port as described, use the port
-you configured.
-
-You will be prompted for a user name and password. Use the user name
-and password you provided in response to the prompts issued during
-the "make instance" process.
-
-If you are using a buildout-based Zope instance, you will need to
-create a user as follows::
-
-  $ bin/zopectl adduser username password
-
-Now you're off and running! You should be looking at the Zope
-management screen which is divided into two frames. On the left you
-can navigate between Zope objects and on the right you can edit them
-by selecting different management functions with the tabs at the top
-of the frame.
-
-If you haven't used Zope before, you should head to the Zope web
-site and read some documentation. The Zope Documentation section is
-a good place to start. You can access it at http://docs.zope.org/
-
-Troubleshooting
-===============
-
-- This version of Zope requires Python 2.6.4 or better.
-  It will *not* run with Python 3.x.
-
-- The Python you run Zope with *must* have threads compiled in,
-  which is the case for a vanilla build.  Warning: Zope will not run
-  with a Python version that uses ``libpth``.  You *must* use
-  ``libpthread``.
-
-- To build Python extensions you need to have Python configuration
-  information available. If your Python comes from an RPM you may
-  need the python-devel (or python-dev) package installed too. If
-  you built Python from source all the configuration information
-  should already be available.
-
-- See the :doc:`CHANGES` for important notes on this version of Zope.
+After installation, refer to :doc:`operation` for documentation on
+configuring and running Zope.

Modified: Zope/branches/2.12/doc/index.rst
===================================================================
--- Zope/branches/2.12/doc/index.rst	2010-03-08 22:49:05 UTC (rev 109857)
+++ Zope/branches/2.12/doc/index.rst	2010-03-08 22:54:01 UTC (rev 109858)
@@ -9,6 +9,8 @@
 
    WHATSNEW.rst
    INSTALL.rst
+   INSTALL-buildout.rst
+   operation.rst
    USERS.rst
    SECURITY.rst
    SETUID.rst

Copied: Zope/branches/2.12/doc/operation.rst (from rev 109567, Zope/branches/tseaver-clarify_install_docs/doc/operation.rst)
===================================================================
--- Zope/branches/2.12/doc/operation.rst	                        (rev 0)
+++ Zope/branches/2.12/doc/operation.rst	2010-03-08 22:54:01 UTC (rev 109858)
@@ -0,0 +1,155 @@
+Configuring and Running Zope
+============================
+
+.. highlight:: bash
+
+
+Whichever method you used to install Zope and create a server instance (see
+:doc:`INSTALL` and :doc:`INSTALL-buildout`), the end result is configured
+and operated the same way.
+
+
+Configuring Zope
+----------------
+
+Your instance's configuration is defined in its ``etc/zope.conf`` file.
+Unless you created the file manually, that file should contain fully-
+annotated examples of each directive.
+
+You can also pass an explicit configuration file on the commandline::
+
+  $ /path/to/zope/instance/bin/zopectl -c /tmp/other.conf show
+  ...
+  Config file:  /tmp/other.conf
+
+When starting Zope, if you see errors indicating that an address is in
+use, then you may have to change the ports Zope uses for HTTP or FTP. 
+The default HTTP and FTP ports used by Zope are
+8080 and 8021 respectively. You can change the ports used by
+editing ./etc/zope.conf appropriately.
+
+The section in the configuration file looks like this::
+
+  <http-server>
+    # valid keys are "address" and "force-connection-close"
+    address 8080
+    # force-connection-close on
+  </http-server>
+
+The address can just be a port number as shown, or a  host:port
+pair to bind only to a specific interface.
+
+After making any changes to the configuration file, you need to restart any
+running Zope server for the affected instance before changes are in effect.
+
+
+Running Zope in the Foreground
+------------------------------
+
+To run Zope without detaching from the console, use the ``fg``
+command (short for ``foreground``)::
+
+  $ /path/to/zope/instance/bin/zopectl fg
+
+In this mode, Zope emits its log messages to the console, and does not
+detach from the terminal.
+
+
+Running Zope as a Daemon
+------------------------
+
+Once an instance home has been created, the Zope server can now be
+started using this command::
+
+  $ /path/to/zope/instance/bin/zopectl start
+
+During startup, Zope emits log messages into
+`/path/to/zope/instance/log/event.log`.  You can examine it with the usual
+tools (``cat``, ``more``, ``tail``, etc) and see if there are any errors
+preventing Zope from starting.
+
+.. highlight:: none
+.. note::
+
+  For this to work on Windows, the Zope instance must be installed as
+  a Service. This is done with::
+
+    bin\zopectl install
+
+  If you later want to remove this Service, do the following::
+
+    bin\zopectl remove
+
+  For the full list of options available for setting up Zope as a
+  Windows Service, do::
+
+    bin\zopectl install --help
+
+.. highlight:: bash
+
+
+Integrating with System Startup
+-------------------------------
+
+zopectl can be linked as rc-script in the usual start directories
+on linux or other System V unix variants.
+
+You can use ``zopectl`` interactively as a command shell by just
+calling it without any arguments. Try ``help`` there and ``help <command>``
+to find out about additionally commands of zopectl. These commands
+also work at the command line.
+
+.. note::
+
+  On Windows, a Service can be installed and set to start
+  automatically with the following:
+
+  .. code-block:: none
+
+    bin\zopectl install --startup=auto
+
+
+Logging In To Zope
+------------------
+
+Once you've started Zope, you can then connect to the Zope webserver
+by directing your browser to::
+
+  http://yourhost:8080/manage
+
+where 'yourhost' is the DNS name or IP address of the machine
+running Zope.  If you changed the HTTP port as described, use the port
+you configured.
+
+You will be prompted for a user name and password. Use the user name
+and password you provided in response to the prompts issued during
+the "make instance" process.
+
+Now you're off and running! You should be looking at the Zope
+management screen which is divided into two frames. On the left you
+can navigate between Zope objects and on the right you can edit them
+by selecting different management functions with the tabs at the top
+of the frame.
+
+If you haven't used Zope before, you should head to the Zope web
+site and read some documentation. The Zope Documentation section is
+a good place to start. You can access it at http://docs.zope.org/
+
+Troubleshooting
+---------------
+
+- This version of Zope requires Python 2.6.4 or better.
+  It will *not* run with Python 3.x.
+
+- The Python you run Zope with *must* have threads compiled in,
+  which is the case for a vanilla build.  Warning: Zope will not run
+  with a Python version that uses ``libpth``.  You *must* use
+  ``libpthread``.
+
+- To build Python extensions you need to have Python configuration
+  information available. If your Python comes from an RPM you may
+  need the python-devel (or python-dev) package installed too. If
+  you built Python from source all the configuration information
+  should already be available.
+
+- See the :doc:`CHANGES` for important notes on this version of Zope.



More information about the checkins mailing list