[Checkins] SVN: z3c.testsetup/trunk/ ongoing documentation cleanup work

Reinout van Rees reinout at vanrees.org
Mon Sep 21 10:42:47 EDT 2009


Log message for revision 104387:
  ongoing documentation cleanup work

Changed:
  U   z3c.testsetup/trunk/DEVELOPMENT.txt
  U   z3c.testsetup/trunk/README.txt
  U   z3c.testsetup/trunk/src/z3c/testsetup/README.txt

-=-
Modified: z3c.testsetup/trunk/DEVELOPMENT.txt
===================================================================
--- z3c.testsetup/trunk/DEVELOPMENT.txt	2009-09-21 14:35:32 UTC (rev 104386)
+++ z3c.testsetup/trunk/DEVELOPMENT.txt	2009-09-21 14:42:47 UTC (rev 104387)
@@ -1,3 +1,20 @@
+Developing on z3c.testsetup itself
+**********************************
+
+Prerequisites
+=============
+
+You need::
+
+- Python 2.4 or 2.5 (status of 2.6 is unknown right now).
+
+- `setuptools`, available from 
+  http://peak.telecommunity.com/DevCenter/setuptools
+
+Other needed packages will be downloaded during installation. Therefore you
+need an internet connection during installation.
+
+
 Installation
 ============
 

Modified: z3c.testsetup/trunk/README.txt
===================================================================
--- z3c.testsetup/trunk/README.txt	2009-09-21 14:35:32 UTC (rev 104386)
+++ z3c.testsetup/trunk/README.txt	2009-09-21 14:42:47 UTC (rev 104387)
@@ -1,103 +1,22 @@
 
-z3c.testsetup
-*************
+z3c.testsetup: easy test setup for zope 3 and python projects
+*************************************************************
 
-is a package that provides some convenience stuff to enable rapid test
-setup for Zope 3 components and normal Python packages. Currently
-doctests (normal unit doctests and functional doctests) and usual
-Python tests made of ``unittest.TestCase`` definitions are supported.
+Setting up tests for Zope 3 projects sometimes tends to be cumbersome. You
+often have to prepare complex things like test layers, setup functions,
+teardown functions and much more. Often these steps have to be done again and
+again.  ``z3c.testsetup`` jumps in here, to support much flatter test
+setups. The package supports normal Python `unit tests
+<http://docs.python.org/library/unittest.html>`_ and `doctests
+<http://docs.python.org/library/doctest.html>`_.
 
-Doctests and test modules are found throughout a whole package and
-registered with sensible, modifiable defaults.
+Doctests and test modules are found throughout a whole package and registered
+with sensible, modifiable defaults.  This saves a lot of manual work!
 
-Also support for reusable test setups is provided by so-called
-TestGetters and TestCollectors.
-
-.. contents::
-
-Setting up doctests (contrary to *writing* those tests) can become
-cumbersome with Zope 3. In the environment you often have to prepare
-complex things like test layers, setup functions, teardown functions
-and much more. Often this steps have to be done again and again.
-
-``z3c.testsetup`` can shorten this work by setting sensible defaults
-for the most important aspects of test setups.
-
-See `README.txt` in the src/z3c/testsetup directory for API
-documentation. There is also extensive documentation for (hopefully)
-every aspect of the package in this directory. See all the .txt files
-to learn more.
-
-Note, that this is alphaware! Do not use it in productive
-environments!
-
-**Important Note:**
-
-  This version of ``z3c.testsetup`` uses a new set of testfile markers
-  than previous releases did. If you are still using `Test-Layer:
-  unit` or similar, please read the README.txt in the source directory
-  carefully to learn how to switch to the new names.
-
-
-Prerequisites
-=============
-
-You need::
-
-- Python 2.4. Rumors are, that also Python 2.5 will do.
-
-- `setuptools`, available from 
-  http://peak.telecommunity.com/DevCenter/setuptools
-
-Other needed packages will be downloaded during
-installation. Therefore you need an internet connection during
-installation. 
-
-
-Installation
-============
-
-From the root of the package run::
-
-     $ python2.4 bootstrap/bootstrap.py
-
-This will download and install everything to run `buildout` in the
-next step. Afterwards an executable script `buildout` should be
-available in the freshly created `bin/` directory.
-
-Next, fetch all needed packages, install them and create provided
-scripts::
-
-     $ bin/buildout
-
-This should create a `test` script in `bin/`.
-
-Running::
-
-     $ bin/test
-
-you can test the installed package.
-
-
-Usage
-=====
-
 See `README.txt` and the other .txt files in the src/z3c/testsetup
-directory for API documentation.
+directory for API documentation. (Or further down this page when reading this
+on pypi).
 
-**Note:** ``z3c.testsetup`` does **not** fetch all packages you might
-  need to run your tests automatically by default. Namely the
-  ``zope.app.testing`` and ``zope.component`` packages are not
-  included if you require only z3c.testsetup in your `setup.py`.
 
-  This is, to make ``z3c.testsetup`` compatible with packages that
-  refuse collaboration when those packages are installed. For
-  instance including ``zope.component`` in the dependencies would
-  exclude Plone developers from using ``z3c.testsetup``.
+.. contents::
 
-  Therefore you must include ``zope.component`` and
-  ``zope.app.testing`` to your ``requires`` list in `setup.py` if you
-  want to use Zope 3 tests. This, however, is done anyway by other
-  packages used in Zope 3 projects and in most cases you do not have
-  to care about this matter.
-

Modified: z3c.testsetup/trunk/src/z3c/testsetup/README.txt
===================================================================
--- z3c.testsetup/trunk/src/z3c/testsetup/README.txt	2009-09-21 14:35:32 UTC (rev 104386)
+++ z3c.testsetup/trunk/src/z3c/testsetup/README.txt	2009-09-21 14:42:47 UTC (rev 104387)
@@ -1,18 +1,12 @@
-Detailed Documentation
+Detailed documentation
 **********************
 
-Easy testsetups for Zope 3 and Python projects.
+Note, that if you want zope integration or functional tests, that you have to
+make sure, that the ``zope.app.testing`` and ``zope.component`` packages are
+available during test runs. ``z3c.testsetup`` does **not** depend on it.  If
+you want zope integration/functional tests, this is almost always already the
+case, so you don't need to care about this.
 
-Setting up tests for Zope 3 projects sometimes tends to be
-cumbersome. ``z3c.testsetup`` jumps in here, to support much flatter
-test setups. The package supports normal Python `unit tests
-<http://docs.python.org/library/unittest.html>`_ and
-`doctests <http://docs.python.org/library/doctest.html>`_.
-
-Note, that if you want integration or functional tests, that you have
-to make sure, that the ``zope.app.testing`` package is available
-during test runs. ``z3c.testsetup`` does **not** depend on it.
-
 The package works in two steps:
 
 1) It looks for testfiles in a given package.
@@ -32,7 +26,15 @@
 `tests/` directory. More details on special topics can be found in the
 appropriate .txt files in this directory.
 
+**Important Note:**
 
+  Between version 0.2 and 0.3 of ``z3c.testsetup`` a new set of testfile
+  markers was introduced. If you are still using `Test-Layer: unit` or
+  similar, please read the README.txt in the source directory carefully to
+  learn how to switch to the new names. (Or see further down this page when
+  reading it on pypi).
+
+
 Basic Example
 =============
 
@@ -472,6 +474,13 @@
     specifying their own layer or ZCML config.
 
 
+**Note:**
+
+  For more elaborate setups, you can use so-called TestGetters and
+  TestCollectors.  They are explained in ``testgetter.txt`` in the source code
+  (so you'll need to look there if you want to use it).
+
+
 Deprectated/unsupported parameters
 ----------------------------------
 



More information about the checkins mailing list