From d48d56613c7311b8532c07272ca7a1cd177a25fa Mon Sep 17 00:00:00 2001
From: jim <jim@62d5b8a3-27da-0310-9561-8e5933582275>
Date: Sat, 27 Oct 2007 16:12:26 +0000
Subject: [PATCH] Added missing doctest for setup command.

Improved error message when no arguments are given to the setup
command.

The setup command no-longer requires a config file.


git-svn-id: http://svn.zope.org/repos/main/zc.buildout/trunk@81136 62d5b8a3-27da-0310-9561-8e5933582275
---
 src/zc/buildout/setup.txt | 49 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 49 insertions(+)
 create mode 100644 src/zc/buildout/setup.txt

diff --git a/src/zc/buildout/setup.txt b/src/zc/buildout/setup.txt
new file mode 100644
index 0000000..885345e
--- /dev/null
+++ b/src/zc/buildout/setup.txt
@@ -0,0 +1,49 @@
+Using zc.buildout to run setup scripts
+======================================
+
+zc buildout has a convenience command for running setup scripts.  Why?
+There are two reasons.  If a setup script doesn't import setuptools,
+you can't use aby setuptools-provided commands, like bdist_egg.  When
+buildut runs a setup script, it arranges to import setuptools before
+running the script so setuptools-provided commands are available.
+
+If you use a squeaky-clean Python to do your development, the a setup
+script that would import setuptools because setuptools isn't in the
+path.  Because buildout requires setuptools and knows where it has
+installed a setuptools egg, it add the setuptools egg to the Python
+path before running the script.  To run a setup script, use the
+buildout setup command, passing the name of a secript or a directory
+containing a setup script and arguments to the script.  Let's look at
+an example:
+
+    >>> mkdir('test')
+    >>> cd('test')
+    >>> write('setup.py',
+    ... '''
+    ... from distutils.core import setup
+    ... setup(name='sample')
+    ... ''')
+
+We've created a super simple (stupid) setup script.  Note that it
+doesn't import setuptools.  Let's try running it to create an egg.
+We'll use the buildout script from our sample buildout:
+
+    >>> print system(buildout+' setup'),
+    Error: The setup command requires the path to a setup script or 
+    directory containing a setup script, and it's arguments.
+
+Oops, we forgot to give the name of the setup script:
+
+    >>> print system(buildout+' setup setup.py bdist_egg'), # doctest: +ELLIPSIS
+    Running setup script 'setup.py'.
+    ...
+
+    >>> ls('dist')
+    -  sample-0.0.0-py2.5.egg
+
+Note that we can specify a directory name.  This is often shorter and
+preferred by the lazy :)
+
+    >>> print system(buildout+' setup . bdist_egg'), # doctest: +ELLIPSIS
+    Running setup script './setup.py'.
+    ...
-- 
2.30.9