[Checkins] SVN: z3c.recipe.compattest/trunk/ added documentation

[Wolfgang Schnerring]

Log message for revision 95298:
  added documentation
  

Changed:
  A   z3c.recipe.compattest/trunk/CHANGES.txt
  U   z3c.recipe.compattest/trunk/setup.py
  U   z3c.recipe.compattest/trunk/src/z3c/recipe/compattest/README.txt

-=-
Added: z3c.recipe.compattest/trunk/CHANGES.txt
===================================================================
--- z3c.recipe.compattest/trunk/CHANGES.txt	                        (rev 0)
+++ z3c.recipe.compattest/trunk/CHANGES.txt	2009-01-28 11:59:58 UTC (rev 95298)
@@ -0,0 +1,8 @@
+=======
+CHANGES
+=======
+
+0.1 (unreleased)
+================
+
+- first released version

Modified: z3c.recipe.compattest/trunk/setup.py
===================================================================
--- z3c.recipe.compattest/trunk/setup.py	2009-01-28 11:55:56 UTC (rev 95297)
+++ z3c.recipe.compattest/trunk/setup.py	2009-01-28 11:59:58 UTC (rev 95298)
@@ -1,36 +1,39 @@
 from setuptools import setup, find_packages
 
 
-setup(name='z3c.recipe.compattest',
-      version = '1.0dev',
-      author='Grok Contributors',
-      author_email='grok-dev at zope.org',
-      description='Tool to create test environement for KGS.',
-      long_description=open(
-        os.path.join('src', 'z3c', 'recipe', 'compattest', 'README.txt')).read(),
-      keywords = "zope3 setuptools egg kgs",
-      classifiers = [
-          'Intended Audience :: Developers',
-          'License :: OSI Approved :: Zope Public License',
-          'Programming Language :: Python',
-          'Operating System :: OS Independent',
-          'Framework :: Zope3'],
-      url='',
-      license='ZPL 2.1',
-      packages=find_packages('src'),
-      package_dir = {'': 'src'},
-      namespace_packages=['z3c', 'z3c.recipe'],
-      install_requires=[
-          'setuptools',
-          'zc.buildout',
-          'zc.recipe.testrunner',
-          ],
-      extras_require=dict(test=[
-            'zope.dottedname',
-          ]),
-      entry_points = {
-          'zc.buildout': ['default = z3c.recipe.compattest.recipe:Recipe'],
-          },
-      include_package_data = True,
-      zip_safe = True,
-      )
+setup(
+    name='z3c.recipe.compattest',
+    version = '0.1dev',
+    author='Grok Contributors',
+    author_email='grok-dev at zope.org',
+    description='Buildout recipe to create testrunners for testing compatibility with other packages',
+    long_description= (
+        open(os.path.join('src', 'z3c', 'recipe', 'compattest', 'README.txt')).read()
+        + '\n\n'
+        + open('CHANGES.txt').read()),
+    keywords = "zope3 setuptools egg kgs",
+    classifiers = [
+        'Intended Audience :: Developers',
+        'License :: OSI Approved :: Zope Public License',
+        'Programming Language :: Python',
+        'Operating System :: OS Independent',
+        'Framework :: Zope3'],
+    url='',
+    license='ZPL 2.1',
+    packages=find_packages('src'),
+    package_dir = {'': 'src'},
+    namespace_packages=['z3c', 'z3c.recipe'],
+    install_requires=[
+        'setuptools',
+        'zc.buildout',
+        'zc.recipe.testrunner',
+        ],
+    extras_require=dict(test=[
+          'zope.dottedname',
+        ]),
+    entry_points = {
+        'zc.buildout': ['default = z3c.recipe.compattest.recipe:Recipe'],
+        },
+    include_package_data = True,
+    zip_safe = False,
+)

Modified: z3c.recipe.compattest/trunk/src/z3c/recipe/compattest/README.txt
===================================================================
--- z3c.recipe.compattest/trunk/src/z3c/recipe/compattest/README.txt	2009-01-28 11:55:56 UTC (rev 95297)
+++ z3c.recipe.compattest/trunk/src/z3c/recipe/compattest/README.txt	2009-01-28 11:59:58 UTC (rev 95298)
@@ -2,6 +2,27 @@
 z3c.recipe.compattest
 =====================
 
+This buildout recipe generates a list of packages to test and a test runner
+that runs each package's tests (isolated from any other tests).
+This is useful to check that the changes made while developing a package
+do not break any packages that are using this package.
+
+Usage
+=====
+
+Add a part to your buildout.cfg that uses this recipe.
+No further configuration is required, but you can set the following options:
+
+ - svn_url: SVN repository to search for packages
+ - include: only packages matching this regex will be included
+   (default: '^zope\..*, ^grokcore\..*')
+ - exclude: packages matching this regex will be excluded, even if they match
+   `include`
+    (default: a list of deprectated/obsolete zope.* packages, see
+    z3c.recipe.compattest.recipe for details)
+ - script: the name of the runner script
+   (default: test-compat)
+
 >>> cd(sample_buildout)
 >>> write('buildout.cfg', """
 ... [buildout]
@@ -11,16 +32,32 @@
 ... recipe = z3c.recipe.compattest
 ... include = z3c.recipe.compattest
 ... """)
+
+For this test, we only include a single package. With the default
+include/exclude values, about 150 packages will be included, so be aware
+that running the buildout will take some time.
+
 >>> system(buildout).find('Installing compattest') != -1
 True
+
+Details
+=======
+
+The recipe generates a test runner for each package, as well as a global runner
+script (called `test-compat` by default) that will run all of them:
+
 >>> ls('bin')
 - buildout
 - compattest-z3c.recipe.compattest
-- test-kgs
+- test-compat
+>>> cat('bin', 'test-compat')
+#!/...python...
+...main(...compattest-z3c.recipe.compattest...
+
+We take care about installing the test dependencies for the packages (from their
+extras_require['test']). Do demonstrate this, we declared a (superfluous) test
+dependency on zope.dottedname, which is picked up:
+
 >>> cat('bin', 'compattest-z3c.recipe.compattest')
 #!/...python...
 ...zope.dottedname...
-
->>> cat('bin', 'test-compat')
-#!/...python...
-...main(...compattest-z3c.recipe.compattest...