docs: Stop using autodoc for t.p.twisted

This way we don't have to install twisted into the docs build
environment. Add some more detail while I'm here.

diff --git a/docs/requirements.in b/docs/requirements.in
index 03e5a69239f79002c39c373bef9036f4f17886a7..334534d739d5f9aee2bf3e58359357bf06015c5e 100644 (file)
--- a/docs/requirements.in
+++ b/docs/requirements.in
@@ -1,4 +1,3 @@
 sphinx
 sphinxcontrib-asyncio
 sphinx_rtd_theme
-Twisted

diff --git a/docs/requirements.txt b/docs/requirements.txt
index 101946c54bbda3d1545d28ed2a7b8987ac2d6395..871d82a85b5b2e43eb827cab30c0e5d60fceb0df 100644 (file)
--- a/docs/requirements.txt
+++ b/docs/requirements.txt
@@ -1,21 +1,15 @@
 alabaster==0.7.12
-attrs==20.2.0
-Automat==20.2.0
 Babel==2.8.0
 certifi==2020.6.20
 chardet==3.0.4
 colorama==0.4.4
-constantly==15.1.0
 docutils==0.16
-hyperlink==20.0.1
 idna==2.10
 imagesize==1.2.0
-incremental==17.5.0
 Jinja2==2.11.2
 MarkupSafe==1.1.1
 packaging==20.4
 Pygments==2.7.2
-PyHamcrest==2.0.2
 pyparsing==2.4.7
 pytz==2020.1
 requests==2.24.0
@@ -30,6 +24,4 @@ sphinxcontrib-htmlhelp==1.0.3
 sphinxcontrib-jsmath==1.0.1
 sphinxcontrib-qthelp==1.0.3
 sphinxcontrib-serializinghtml==1.1.4
-Twisted==20.3.0
 urllib3==1.25.11
-zope.interface==5.1.2

diff --git a/docs/twisted.rst b/docs/twisted.rst
index a5d971a04028ed2dafa6fdeebbbbe9c98509eb90..f834eb55b212eabc845f74216d65cf59411ac8fa 100644 (file)
--- a/docs/twisted.rst
+++ b/docs/twisted.rst
@@ -1,10 +1,55 @@
 ``tornado.platform.twisted`` --- Bridges between Twisted and Tornado
-========================================================================
+====================================================================
 
-.. automodule:: tornado.platform.twisted
+.. module:: tornado.platform.twisted
 
-   Twisted DNS resolver
-   --------------------
+.. deprecated:: 6.0
 
-   .. autoclass:: TwistedResolver
-      :members:
+   This module is no longer recommended for new code. Instead of using
+   direct integration between Tornado and Twisted, new applications should
+   rely on the integration with ``asyncio`` provided by both packages.
+
+Importing this module has the side effect of registering Twisted's ``Deferred``
+class with Tornado's ``@gen.coroutine`` so that ``Deferred`` objects can be
+used with ``yield`` in coroutines using this decorator (importing this module has
+no effect on native coroutines using ``async def``). 
+
+.. function:: install()
+
+    Install ``AsyncioSelectorReactor`` as the default Twisted reactor.
+
+    .. deprecated:: 5.1
+
+       This function is provided for backwards compatibility; code
+       that does not require compatibility with older versions of
+       Tornado should use
+       ``twisted.internet.asyncioreactor.install()`` directly.
+
+    .. versionchanged:: 6.0.3
+
+       In Tornado 5.x and before, this function installed a reactor
+       based on the Tornado ``IOLoop``. When that reactor
+       implementation was removed in Tornado 6.0.0, this function was
+       removed as well. It was restored in Tornado 6.0.3 using the
+       ``asyncio`` reactor instead.
+
+Twisted DNS resolver
+--------------------
+
+.. class:: TwistedResolver
+
+    Twisted-based asynchronous resolver.
+
+    This is a non-blocking and non-threaded resolver.  It is
+    recommended only when threads cannot be used, since it has
+    limitations compared to the standard ``getaddrinfo``-based
+    `~tornado.netutil.Resolver` and
+    `~tornado.netutil.DefaultExecutorResolver`.  Specifically, it returns at
+    most one result, and arguments other than ``host`` and ``family``
+    are ignored.  It may fail to resolve when ``family`` is not
+    ``socket.AF_UNSPEC``.
+
+    Requires Twisted 12.1 or newer.
+
+    .. versionchanged:: 5.0
+       The ``io_loop`` argument (deprecated since version 4.1) has been removed.