Move Twisted docs to separate file

doc/for-test-authors.rst

@@ -1253,51 +1253,8 @@ in case it is needed.
 Twisted support
 ---------------
 
-testtools provides *highly experimental* support for running Twisted tests –
-tests that return a Deferred_ and rely on the Twisted reactor.  You should not
-use this feature right now.  We reserve the right to change the API and
-behaviour without telling you first.
-
-However, if you are going to, here's how you do it::
-
-  from testtools import TestCase
-  from testtools.deferredruntest import AsynchronousDeferredRunTest
-
-  class MyTwistedTests(TestCase):
-
-      run_tests_with = AsynchronousDeferredRunTest
-
-      def test_foo(self):
-          # ...
-          return d
-
-In particular, note that you do *not* have to use a special base ``TestCase``
-in order to run Twisted tests.
-
-You can also run individual tests within a test case class using the Twisted
-test runner::
-
-   class MyTestsSomeOfWhichAreTwisted(TestCase):
-
-       def test_normal(self):
-           pass
-
-       @run_test_with(AsynchronousDeferredRunTest)
-       def test_twisted(self):
-           # ...
-           return d
-
-Here are some tips for converting your Trial tests into testtools tests.
-
-* Use the ``AsynchronousDeferredRunTest`` runner
-* Make sure to upcall to ``setUp`` and ``tearDown``
-* Don't use ``setUpClass`` or ``tearDownClass``
-* Don't expect setting .todo, .timeout or .skip attributes to do anything
-* ``flushLoggedErrors`` is ``testtools.deferredruntest.flush_logged_errors``
-* ``assertFailure`` is ``testtools.deferredruntest.assert_fails_with``
-* Trial spins the reactor a couple of times before cleaning it up,
-  ``AsynchronousDeferredRunTest`` does not.  If you rely on this behavior, use
-  ``AsynchronousDeferredRunTestForBrokenTwisted``.
+testtools provides support for running Twisted tests – tests that return a
+Deferred_ and rely on the Twisted reactor. See (XXX - jml - insert link)
 
 force_failure
 -------------
@@ -1480,7 +1437,6 @@ Here, ``repr(nullary)`` will be the same as ``repr(f)``.
 .. _fixtures: http://pypi.python.org/pypi/fixtures
 .. _unittest: http://docs.python.org/library/unittest.html
 .. _doctest: http://docs.python.org/library/doctest.html
-.. _Deferred: http://twistedmatrix.com/documents/current/core/howto/defer.html
 .. _discover: http://pypi.python.org/pypi/discover
 .. _Distutils: http://docs.python.org/library/distutils.html
 .. _`setup configuration`: http://docs.python.org/distutils/configfile.html

doc/index.rst

@@ -23,6 +23,7 @@ Contents:
    overview
    for-test-authors
    for-framework-folk
+   twisted-support
    hacking
    Changes to testtools <news>
    API reference documentation <api>

doc/twisted-support.rst

@@ -0,0 +1,52 @@
+Twisted support
+===============
+
+testtools provides support for running Twisted tests – tests that return a
+Deferred_ and rely on the Twisted reactor.
+
+You should not use this feature right now. We reserve the right to change the
+API and behaviour without telling you first.
+
+However, if you are going to, here's how you do it::
+
+  from testtools import TestCase
+  from testtools.deferredruntest import AsynchronousDeferredRunTest
+
+  class MyTwistedTests(TestCase):
+
+      run_tests_with = AsynchronousDeferredRunTest
+
+      def test_foo(self):
+          # ...
+          return d
+
+In particular, note that you do *not* have to use a special base ``TestCase``
+in order to run Twisted tests.
+
+You can also run individual tests within a test case class using the Twisted
+test runner::
+
+   class MyTestsSomeOfWhichAreTwisted(TestCase):
+
+       def test_normal(self):
+           pass
+
+       @run_test_with(AsynchronousDeferredRunTest)
+       def test_twisted(self):
+           # ...
+           return d
+
+Here are some tips for converting your Trial tests into testtools tests.
+
+* Use the ``AsynchronousDeferredRunTest`` runner
+* Make sure to upcall to ``setUp`` and ``tearDown``
+* Don't use ``setUpClass`` or ``tearDownClass``
+* Don't expect setting .todo, .timeout or .skip attributes to do anything
+* ``flushLoggedErrors`` is ``testtools.deferredruntest.flush_logged_errors``
+* ``assertFailure`` is ``testtools.deferredruntest.assert_fails_with``
+* Trial spins the reactor a couple of times before cleaning it up,
+  ``AsynchronousDeferredRunTest`` does not.  If you rely on this behavior, use
+  ``AsynchronousDeferredRunTestForBrokenTwisted``.
+
+
+.. _Deferred: http://twistedmatrix.com/documents/current/core/howto/defer.html