From 385680011b16f266d5994dc69b5fffe3e403bdf1 Mon Sep 17 00:00:00 2001
From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Fri, 25 Jun 2004 12:56:28 +0000
Subject: moved documentation for testing to docs/dev/testing.txt

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2369 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/testing.txt | 137 +++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 137 insertions(+)
 create mode 100644 docs/dev/testing.txt

(limited to 'docs/dev/testing.txt')

diff --git a/docs/dev/testing.txt b/docs/dev/testing.txt
new file mode 100644
index 000000000..8cca49cac
--- /dev/null
+++ b/docs/dev/testing.txt
@@ -0,0 +1,137 @@
+=======
+Testing
+=======
+
+:Author: Felix Wiemann
+:Revision: $Revision$
+:Date: $Date$
+:Copyright: This document has been placed in the public domain.
+
+.. contents::
+
+This document describes how the tests are organized and how to add new
+tests or modify existing tests.
+
+
+Unit Tests
+==========
+
+Unit tests test single functions or modules (i.e. whitebox testing).
+
+XXX Some details to be written.
+
+Setting Up For Testing
+----------------------
+
+Recent versions of Python's ``unittest.py`` module have an annoying
+new "feature", where newlines in test failure output are displayed as
+"\n" (two characters) instead of as actual newlines.  This means that
+test failure output is unreadable and unuseable.  Earlier versions
+didn't have this feature, and the output could easily be copied and
+pasted into test data modules.  Revision `1.7.2.1 of unittest.py`__
+works well.  Download it, place it in the ``test/`` directory, and
+enjoy much better output.
+
+__ http://cvs.sf.net/viewcvs.py/*checkout*/python/python/dist/src/Lib/unittest.py?rev=1.7.2.1
+
+
+.. _functional::
+
+Functional Tests
+================
+
+The directory ``test/functional/`` contains data for functional tests.
+
+Performing functional testing means testing the Docutils system as a
+whole (i.e. blackbox testing).
+
+Directory Structure
+-------------------
+
++ ``functional/`` The main data directory.
+
+  + ``input/`` The input files.
+
+    - ``some_test.txt``, for example.
+
+  + ``output/`` The actual output.
+
+    - ``some_test.html``, for example.
+
+  + ``expected/`` The expected output.
+
+    - ``some_test.html``, for example.
+
+  + ``tests/`` The config files for processing the input files.
+
+    - ``some_test.py``, for example.
+
+    - ``_default.py``, the `default configuration file`_.
+
+The Testing Process
+-------------------
+
+When running ``test_functional.py``, all config files in
+``functional/some_test.py`` are processed.
+
+An example of what this means:
+
+Provided ``functional/tests/some_test.py`` reads like this::
+
+    # Source and destination file names.
+    test_source = "some_test.txt"
+    test_destination = "some_test.html"
+
+    # Keyword parameters passed to publish_file.
+    reader_name = "standalone"
+    parser_name = "rst"
+    writer_name = "html"
+    settings_overrides['output-encoding'] = 'utf-8'
+
+The two variables ``test_source`` and ``test_destination`` contain the
+input file name (relative to ``functional/input/``) and the output
+file name (relative to ``functional/output/`` and
+``functional/expected/``).  Note that the file names can be chosen
+arbitrarily.  However, the file names in ``functional/output/`` *must*
+match the file names in ``functional/expected/``.
+
+All other variables are passed as keyword arguments to
+``docutils.core.publish_file``, so you can set reader, parser,
+writer and anything else you want to configure.
+
+Note that ``settings_overrides`` is already initialized as an empty
+dictionary *before* the execution of the config file.  This is done in
+order to allow subsequent assignments to ``settings_overrides`` in the
+`default configuration file`_ and in the actual configuration file.
+
+Creating New Tests
+------------------
+
+In order to create a new test, put the input test file into
+``functional/input/``.  Then create a config file in
+``functional/tests/`` which sets at least input and output file names,
+reader, parser and writer.
+
+Now run ``test_functional.py``.  The test will fail, of course,
+because you do not have an expected output yet.
+
+However, an output file will be generated in ``functional/output/``.
+Check this output file for validity and correctness.  Then copy the
+file to ``functional/expected/``.
+
+If you run ``test_functional.py`` later and the actual output doesn't
+match the expected output anymore, the test will fail.
+
+If this is the case and you made an intentional change, check the
+actual output for validity and correctness and copy it to
+``functional/expected/``, overwriting the old expected output.
+
+.. _default configuration file:
+
+The Default Configuration File
+------------------------------
+
+The file ``functional/tests/_default.py`` contains default settings.
+It is executed just before the actual configuration files, which has
+the same effect as if the contents of ``_default.py`` were prepended
+to every configuration file.
-- 
cgit v1.2.1


From 603d413e2405eff19d197d70f56ffd1b287b0e3d Mon Sep 17 00:00:00 2001
From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Sun, 27 Jun 2004 14:37:24 +0000
Subject: updated

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2399 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/testing.txt | 8 +++++---
 1 file changed, 5 insertions(+), 3 deletions(-)

(limited to 'docs/dev/testing.txt')

diff --git a/docs/dev/testing.txt b/docs/dev/testing.txt
index 8cca49cac..f35ef221a 100644
--- a/docs/dev/testing.txt
+++ b/docs/dev/testing.txt
@@ -1,12 +1,14 @@
-=======
-Testing
-=======
+===================
+ Docutils_ Testing
+===================
 
 :Author: Felix Wiemann
 :Revision: $Revision$
 :Date: $Date$
 :Copyright: This document has been placed in the public domain.
 
+.. _Docutils: http://docutils.sourceforge.net/
+
 .. contents::
 
 This document describes how the tests are organized and how to add new
-- 
cgit v1.2.1


From bf77d5ccc2301ca8c26efc293c873ab63be0bde8 Mon Sep 17 00:00:00 2001
From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Tue, 27 Jul 2004 20:48:52 +0000
Subject: fix for backslash

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2483 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/testing.txt | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

(limited to 'docs/dev/testing.txt')

diff --git a/docs/dev/testing.txt b/docs/dev/testing.txt
index f35ef221a..5941f0de6 100644
--- a/docs/dev/testing.txt
+++ b/docs/dev/testing.txt
@@ -27,12 +27,12 @@ Setting Up For Testing
 
 Recent versions of Python's ``unittest.py`` module have an annoying
 new "feature", where newlines in test failure output are displayed as
-"\n" (two characters) instead of as actual newlines.  This means that
-test failure output is unreadable and unuseable.  Earlier versions
-didn't have this feature, and the output could easily be copied and
-pasted into test data modules.  Revision `1.7.2.1 of unittest.py`__
-works well.  Download it, place it in the ``test/`` directory, and
-enjoy much better output.
+``\n`` (two characters) instead of as actual newlines.  This means
+that test failure output is unreadable and unuseable.  Earlier
+versions didn't have this feature, and the output could easily be
+copied and pasted into test data modules.  Revision `1.7.2.1 of
+unittest.py`__ works well.  Download it, place it in the ``test/``
+directory, and enjoy much better output.
 
 __ http://cvs.sf.net/viewcvs.py/*checkout*/python/python/dist/src/Lib/unittest.py?rev=1.7.2.1
 
-- 
cgit v1.2.1


From 7a22203ce9494ee5716140374d7869795f4af307 Mon Sep 17 00:00:00 2001
From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Sun, 29 Aug 2004 12:05:13 +0000
Subject: some fixes

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2544 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/testing.txt | 21 +++++++++------------
 1 file changed, 9 insertions(+), 12 deletions(-)

(limited to 'docs/dev/testing.txt')

diff --git a/docs/dev/testing.txt b/docs/dev/testing.txt
index 5941f0de6..d11d42983 100644
--- a/docs/dev/testing.txt
+++ b/docs/dev/testing.txt
@@ -74,11 +74,9 @@ The Testing Process
 -------------------
 
 When running ``test_functional.py``, all config files in
-``functional/some_test.py`` are processed.
+``functional/tests/`` are processed.
 
-An example of what this means:
-
-Provided ``functional/tests/some_test.py`` reads like this::
+For example, ``functional/tests/some_test.py`` could read like this::
 
     # Source and destination file names.
     test_source = "some_test.txt"
@@ -101,10 +99,8 @@ All other variables are passed as keyword arguments to
 ``docutils.core.publish_file``, so you can set reader, parser,
 writer and anything else you want to configure.
 
-Note that ``settings_overrides`` is already initialized as an empty
-dictionary *before* the execution of the config file.  This is done in
-order to allow subsequent assignments to ``settings_overrides`` in the
-`default configuration file`_ and in the actual configuration file.
+Note that ``settings_overrides`` is already initialized as a
+dictionary *before* the execution of the config file.
 
 Creating New Tests
 ------------------
@@ -115,11 +111,12 @@ In order to create a new test, put the input test file into
 reader, parser and writer.
 
 Now run ``test_functional.py``.  The test will fail, of course,
-because you do not have an expected output yet.
+because you do not have an expected output yet.  However, an output
+file will have been generated in ``functional/output/``.  Check this
+output file for validity and correctness.  Then copy the file to
+``functional/expected/``.
 
-However, an output file will be generated in ``functional/output/``.
-Check this output file for validity and correctness.  Then copy the
-file to ``functional/expected/``.
+If you rerun ``test_functional.py`` now, it should pass.
 
 If you run ``test_functional.py`` later and the actual output doesn't
 match the expected output anymore, the test will fail.
-- 
cgit v1.2.1


From 63f9dc2460332a7bb37463f5b94102ceefc7a050 Mon Sep 17 00:00:00 2001
From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Wed, 1 Sep 2004 15:43:19 +0000
Subject: added some documentation about unit tests

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2551 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/testing.txt | 57 +++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 56 insertions(+), 1 deletion(-)

(limited to 'docs/dev/testing.txt')

diff --git a/docs/dev/testing.txt b/docs/dev/testing.txt
index d11d42983..c05ad59dd 100644
--- a/docs/dev/testing.txt
+++ b/docs/dev/testing.txt
@@ -20,7 +20,14 @@ Unit Tests
 
 Unit tests test single functions or modules (i.e. whitebox testing).
 
-XXX Some details to be written.
+If you are implementing a new feature, be sure to write a test case
+covering its functionality.  It happens very frequently that your
+implementation (or even only a part of it) doesn't work with an older
+(or even newer) Python version, and the only reliable way to detect
+those cases is using tests.
+
+Often, it's easier to write the test first and then implement the
+functionality required to make the test pass.
 
 Setting Up For Testing
 ----------------------
@@ -36,6 +43,54 @@ directory, and enjoy much better output.
 
 __ http://cvs.sf.net/viewcvs.py/*checkout*/python/python/dist/src/Lib/unittest.py?rev=1.7.2.1
 
+Writing New Tests
+-----------------
+
+When writing new tests, it very often helps to see how a similar test
+is implemented.  For example, the files in the
+``test_parsers/test_rst/`` directory all look very similar.  So when
+adding a test, you don't have to reinvent the wheel.
+
+If there is no similar test, you can write a new test from scratch
+using Python's ``unittest`` module.  For an example, please have a
+look at the following imaginary ``test_square.py``::
+
+    #! /usr/bin/env python
+
+    # Author: your name
+    # Contact: your email address
+    # Revision: $Revision$
+    # Date: $Date$
+    # Copyright: This module has been placed in the public domain.
+
+    """
+    Test module for docutils.square.
+    """
+
+    import unittest
+    import docutils.square
+
+
+    class SquareTest(unittest.TestCase):
+
+        def test_square(self):
+            self.assertEqual(docutils.square.square(0), 0)
+            self.assertEqual(docutils.square.square(5), 25)
+            self.assertEqual(docutils.square.square(7), 49)
+
+        def test_square_root(self):
+            self.assertEqual(docutils.square.sqrt(49), 7)
+            self.assertEqual(docutils.square.sqrt(0), 0)
+            self.assertRaises(docutils.square.SquareRootError,
+                              docutils.square.sqrt, 20)
+            
+
+    if __name__ == '__main__':
+        unittest.main()
+
+For more details on how to write tests, please refer to the
+documentation of the ``unittest`` module.
+
 
 .. _functional::
 
-- 
cgit v1.2.1


From 9a36a5e1149753ce6254534c406d5d49d7b993af Mon Sep 17 00:00:00 2001
From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Thu, 9 Sep 2004 21:12:56 +0000
Subject: updated

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2563 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/testing.txt | 13 ++++++++++---
 1 file changed, 10 insertions(+), 3 deletions(-)

(limited to 'docs/dev/testing.txt')

diff --git a/docs/dev/testing.txt b/docs/dev/testing.txt
index c05ad59dd..4e4a04518 100644
--- a/docs/dev/testing.txt
+++ b/docs/dev/testing.txt
@@ -29,6 +29,7 @@ those cases is using tests.
 Often, it's easier to write the test first and then implement the
 functionality required to make the test pass.
 
+
 Setting Up For Testing
 ----------------------
 
@@ -43,6 +44,7 @@ directory, and enjoy much better output.
 
 __ http://cvs.sf.net/viewcvs.py/*checkout*/python/python/dist/src/Lib/unittest.py?rev=1.7.2.1
 
+
 Writing New Tests
 -----------------
 
@@ -83,7 +85,7 @@ look at the following imaginary ``test_square.py``::
             self.assertEqual(docutils.square.sqrt(0), 0)
             self.assertRaises(docutils.square.SquareRootError,
                               docutils.square.sqrt, 20)
-            
+
 
     if __name__ == '__main__':
         unittest.main()
@@ -102,6 +104,7 @@ The directory ``test/functional/`` contains data for functional tests.
 Performing functional testing means testing the Docutils system as a
 whole (i.e. blackbox testing).
 
+
 Directory Structure
 -------------------
 
@@ -125,6 +128,7 @@ Directory Structure
 
     - ``_default.py``, the `default configuration file`_.
 
+
 The Testing Process
 -------------------
 
@@ -157,6 +161,7 @@ writer and anything else you want to configure.
 Note that ``settings_overrides`` is already initialized as a
 dictionary *before* the execution of the config file.
 
+
 Creating New Tests
 ------------------
 
@@ -177,8 +182,10 @@ If you run ``test_functional.py`` later and the actual output doesn't
 match the expected output anymore, the test will fail.
 
 If this is the case and you made an intentional change, check the
-actual output for validity and correctness and copy it to
-``functional/expected/``, overwriting the old expected output.
+actual output for validity and correctness, copy it to
+``functional/expected/`` (overwriting the old expected output), and
+commit the change to CVS.
+
 
 .. _default configuration file:
 
-- 
cgit v1.2.1


From a42cca696d0be3d2c7f022d784890c8f2955e00e Mon Sep 17 00:00:00 2001
From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Mon, 13 Sep 2004 18:22:15 +0000
Subject: removed section about ugly unittest output, because it's fixed in
 DocutilsTestSupport

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2606 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/testing.txt | 15 ---------------
 1 file changed, 15 deletions(-)

(limited to 'docs/dev/testing.txt')

diff --git a/docs/dev/testing.txt b/docs/dev/testing.txt
index 4e4a04518..53faff37e 100644
--- a/docs/dev/testing.txt
+++ b/docs/dev/testing.txt
@@ -30,21 +30,6 @@ Often, it's easier to write the test first and then implement the
 functionality required to make the test pass.
 
 
-Setting Up For Testing
-----------------------
-
-Recent versions of Python's ``unittest.py`` module have an annoying
-new "feature", where newlines in test failure output are displayed as
-``\n`` (two characters) instead of as actual newlines.  This means
-that test failure output is unreadable and unuseable.  Earlier
-versions didn't have this feature, and the output could easily be
-copied and pasted into test data modules.  Revision `1.7.2.1 of
-unittest.py`__ works well.  Download it, place it in the ``test/``
-directory, and enjoy much better output.
-
-__ http://cvs.sf.net/viewcvs.py/*checkout*/python/python/dist/src/Lib/unittest.py?rev=1.7.2.1
-
-
 Writing New Tests
 -----------------
 
-- 
cgit v1.2.1


From 0a9a7c9ed49f0a3320ffeba38df3a06a3424ad2f Mon Sep 17 00:00:00 2001
From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Wed, 25 May 2005 23:41:17 +0000
Subject: some updates of doc files from CVS to SVN

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3363 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/testing.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

(limited to 'docs/dev/testing.txt')

diff --git a/docs/dev/testing.txt b/docs/dev/testing.txt
index 53faff37e..c3e9486c6 100644
--- a/docs/dev/testing.txt
+++ b/docs/dev/testing.txt
@@ -169,7 +169,7 @@ match the expected output anymore, the test will fail.
 If this is the case and you made an intentional change, check the
 actual output for validity and correctness, copy it to
 ``functional/expected/`` (overwriting the old expected output), and
-commit the change to CVS.
+commit the change.
 
 
 .. _default configuration file:
-- 
cgit v1.2.1


From 4e18a9066509d7a767315773806789e589fb49ac Mon Sep 17 00:00:00 2001
From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Wed, 25 May 2005 23:44:08 +0000
Subject: documented ignoring of functional test config files which start with
 an underscore

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3364 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/testing.txt | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

(limited to 'docs/dev/testing.txt')

diff --git a/docs/dev/testing.txt b/docs/dev/testing.txt
index c3e9486c6..cc4f4881d 100644
--- a/docs/dev/testing.txt
+++ b/docs/dev/testing.txt
@@ -118,7 +118,8 @@ The Testing Process
 -------------------
 
 When running ``test_functional.py``, all config files in
-``functional/tests/`` are processed.
+``functional/tests/`` are processed.  (Config files whose names begin
+with an underscore are ignored.)
 
 For example, ``functional/tests/some_test.py`` could read like this::
 
-- 
cgit v1.2.1


From addb725de29a5e58a7c82d3d070c9a0b2b20704a Mon Sep 17 00:00:00 2001
From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Wed, 25 May 2005 23:58:09 +0000
Subject: added information about working directory

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3365 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/testing.txt | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

(limited to 'docs/dev/testing.txt')

diff --git a/docs/dev/testing.txt b/docs/dev/testing.txt
index cc4f4881d..9feac9c6a 100644
--- a/docs/dev/testing.txt
+++ b/docs/dev/testing.txt
@@ -119,7 +119,8 @@ The Testing Process
 
 When running ``test_functional.py``, all config files in
 ``functional/tests/`` are processed.  (Config files whose names begin
-with an underscore are ignored.)
+with an underscore are ignored.)  The current working directory is
+always Docutils' main test directory (``test/``).
 
 For example, ``functional/tests/some_test.py`` could read like this::
 
@@ -132,6 +133,8 @@ For example, ``functional/tests/some_test.py`` could read like this::
     parser_name = "rst"
     writer_name = "html"
     settings_overrides['output-encoding'] = 'utf-8'
+    # Relative to main ``test/`` directory.
+    settings_overrides['stylesheet_path'] = '../tools/stylesheets/default.css'
 
 The two variables ``test_source`` and ``test_destination`` contain the
 input file name (relative to ``functional/input/``) and the output
-- 
cgit v1.2.1


From c01aad4e43f778039596074edfe1989e14701290 Mon Sep 17 00:00:00 2001
From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Tue, 20 Sep 2005 20:06:17 +0000
Subject: fixed malformed hyperlink target

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3893 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/testing.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

(limited to 'docs/dev/testing.txt')

diff --git a/docs/dev/testing.txt b/docs/dev/testing.txt
index 9feac9c6a..681cb7ae9 100644
--- a/docs/dev/testing.txt
+++ b/docs/dev/testing.txt
@@ -79,7 +79,7 @@ For more details on how to write tests, please refer to the
 documentation of the ``unittest`` module.
 
 
-.. _functional::
+.. _functional:
 
 Functional Tests
 ================
-- 
cgit v1.2.1


From 5da7532801abf44378d5422760ab68a84bc39fbc Mon Sep 17 00:00:00 2001
From: wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Tue, 11 Oct 2005 23:00:39 +0000
Subject: removed references to default.css; to-do: update PEP writer (->
 pep.css) and then docs/user/tools.txt

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3940 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/testing.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

(limited to 'docs/dev/testing.txt')

diff --git a/docs/dev/testing.txt b/docs/dev/testing.txt
index 681cb7ae9..fc6feae2b 100644
--- a/docs/dev/testing.txt
+++ b/docs/dev/testing.txt
@@ -134,7 +134,7 @@ For example, ``functional/tests/some_test.py`` could read like this::
     writer_name = "html"
     settings_overrides['output-encoding'] = 'utf-8'
     # Relative to main ``test/`` directory.
-    settings_overrides['stylesheet_path'] = '../tools/stylesheets/default.css'
+    settings_overrides['stylesheet_path'] = '../docutils/writers/support/html4css1.css'
 
 The two variables ``test_source`` and ``test_destination`` contain the
 input file name (relative to ``functional/input/``) and the output
-- 
cgit v1.2.1


From 346f8dfa0961a46400be6764ea74337b5e13c7b6 Mon Sep 17 00:00:00 2001
From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Fri, 28 Oct 2005 16:12:07 +0000
Subject: updated the project policies for trunk/branch development & version
 numbering

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3961 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/testing.txt | 54 ++++++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 52 insertions(+), 2 deletions(-)

(limited to 'docs/dev/testing.txt')

diff --git a/docs/dev/testing.txt b/docs/dev/testing.txt
index fc6feae2b..6963f6541 100644
--- a/docs/dev/testing.txt
+++ b/docs/dev/testing.txt
@@ -3,6 +3,7 @@
 ===================
 
 :Author: Felix Wiemann
+:Author: David Goodger
 :Revision: $Revision$
 :Date: $Date$
 :Copyright: This document has been placed in the public domain.
@@ -11,8 +12,57 @@
 
 .. contents::
 
-This document describes how the tests are organized and how to add new
-tests or modify existing tests.
+When adding new functionality (or fixing bugs), be sure to add test
+cases to the test suite.  Practise test-first programming; it's fun,
+it's addictive, and it works!
+
+This document describes how to run the Docutils test suite, how the
+tests are organized and how to add new tests or modify existing tests.
+
+
+Running the Test Suite
+======================
+
+Before checking in any changes, run the entire Docutils test suite to
+be sure that you haven't broken anything.  From a shell::
+
+    cd docutils/test
+    ./alltests.py
+
+
+Python Versions
+===============
+
+The Docutils 0.4 release supports Python 2.1 [#py21]_ or later, with
+some features only working (and being tested) with Python 2.3+.
+Therefore, you should actually have Pythons 2.1 [#py21]_, 2.2, 2.3, as
+well as the latest Python installed and always run the tests on all of
+them.  (A good way to do that is to always run the test suite through
+a short script that runs ``alltests.py`` under each version of
+Python.)  If you can't afford intalling 3 or more Python versions, the
+edge cases (2.1 and 2.3) should cover most of it.
+
+.. [#py21] Python 2.1 may be used providing the compiler package is
+   installed.  The compiler package can be found in the Tools/
+   directory of Python 2.1's source distribution.
+
+Good resources covering the differences between Python versions:
+
+* `What's New in Python 2.2`__
+* `What's New in Python 2.3`__
+* `What's New in Python 2.4`__
+* `PEP 290 - Code Migration and Modernization`__
+
+__ http://www.python.org/doc/2.2.3/whatsnew/whatsnew22.html
+__ http://www.python.org/doc/2.3.5/whatsnew/whatsnew23.html
+__ http://www.python.org/doc/2.4.1/whatsnew/whatsnew24.html
+__ http://www.python.org/peps/pep-0290.html
+
+.. _Python Check-in Policies: http://www.python.org/dev/tools.html
+.. _sandbox directory:
+   http://svn.berlios.de/viewcvs/docutils/trunk/sandbox/
+.. _nightly repository tarball:
+   http://svn.berlios.de/svndumps/docutils-repos.gz
 
 
 Unit Tests
-- 
cgit v1.2.1


From 118dd3d2aa36cf563590197e28830c1a905f9cd8 Mon Sep 17 00:00:00 2001
From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Thu, 8 Dec 2005 04:43:13 +0000
Subject: merged branches/s5 changes r4011:4155 into trunk/docutils

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@4156 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/testing.txt | 19 ++++++++++++++-----
 1 file changed, 14 insertions(+), 5 deletions(-)

(limited to 'docs/dev/testing.txt')

diff --git a/docs/dev/testing.txt b/docs/dev/testing.txt
index 6963f6541..82e9ed31c 100644
--- a/docs/dev/testing.txt
+++ b/docs/dev/testing.txt
@@ -193,12 +193,21 @@ file name (relative to ``functional/output/`` and
 arbitrarily.  However, the file names in ``functional/output/`` *must*
 match the file names in ``functional/expected/``.
 
-All other variables are passed as keyword arguments to
-``docutils.core.publish_file``, so you can set reader, parser,
-writer and anything else you want to configure.
+If defined, ``_test_more`` must be a function with the following
+signature::
 
-Note that ``settings_overrides`` is already initialized as a
-dictionary *before* the execution of the config file.
+    def _test_more(expected_dir, output_dir, test_case, parameters):
+
+This function is called from the test case to perform tests beyond the
+simple comparison of expected and actual output files.
+
+``test_source`` and ``test_destination`` are removed from the
+namespace, as are all variables whose names begin with an underscore
+("_").  The remaining names are passed as keyword arguments to
+``docutils.core.publish_file``, so you can set reader, parser, writer
+and anything else you want to configure.  Note that
+``settings_overrides`` is already initialized as a dictionary *before*
+the execution of the config file.
 
 
 Creating New Tests
-- 
cgit v1.2.1


From c2737d5c145b4715cf6ed0b4fd9362e07d50b86b Mon Sep 17 00:00:00 2001
From: goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Fri, 9 Dec 2005 04:21:34 +0000
Subject: Converted ``docutils/writers/support/`` into individual writer
 packages; updated docs & refs.

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@4163 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docs/dev/testing.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

(limited to 'docs/dev/testing.txt')

diff --git a/docs/dev/testing.txt b/docs/dev/testing.txt
index 82e9ed31c..bde54116f 100644
--- a/docs/dev/testing.txt
+++ b/docs/dev/testing.txt
@@ -184,7 +184,7 @@ For example, ``functional/tests/some_test.py`` could read like this::
     writer_name = "html"
     settings_overrides['output-encoding'] = 'utf-8'
     # Relative to main ``test/`` directory.
-    settings_overrides['stylesheet_path'] = '../docutils/writers/support/html4css1.css'
+    settings_overrides['stylesheet_path'] = '../docutils/writers/html4css1/html4css1.css'
 
 The two variables ``test_source`` and ``test_destination`` contain the
 input file name (relative to ``functional/input/``) and the output
-- 
cgit v1.2.1