document Trio code

diff --git a/doc/manual.rst b/doc/manual.rst
index 440eafd993ca434546ed4361385d0c0c0873b88e..48243facdf95ae7cdf900609c2dd0ddc3734d788 100644 (file)
--- a/doc/manual.rst
+++ b/doc/manual.rst
@@ -12,5 +12,6 @@ Dnspython Manual
    resolver
    zone
    dnssec
+   trio
    exceptions
    utilities

diff --git a/doc/trio-query.rst b/doc/trio-query.rst
new file mode 100644 (file)
index 0000000..d4d0392
--- /dev/null
+++ b/doc/trio-query.rst
@@ -0,0 +1,28 @@
+.. module:: dns.trio.query
+.. _trio-query:
+
+DNS Query Support
+=================
+
+The ``dns.trio.query`` module is for sending messages to DNS servers, and
+processing their responses.  If you want "stub resolver" behavior, then
+you should use the higher level ``dns.trio.resolver`` module; see
+:ref:`trio_resolver`.
+
+There is currently no support for zone transfers or DNS-over-HTTPS
+using Trio, but we hope to offer this in the future.
+
+UDP
+---
+
+.. autofunction:: dns.trio.query.udp
+.. autofunction:: dns.trio.query.udp_with_fallback
+.. autofunction:: dns.trio.query.send_udp
+.. autofunction:: dns.trio.query.receive_udp
+
+Streams (TCP and TLS)
+---------------------
+
+.. autofunction:: dns.trio.query.stream
+.. autofunction:: dns.trio.query.send_stream
+.. autofunction:: dns.trio.query.receive_stream

diff --git a/doc/trio-resolver-class.rst b/doc/trio-resolver-class.rst
new file mode 100644 (file)
index 0000000..537c933
--- /dev/null
+++ b/doc/trio-resolver-class.rst
@@ -0,0 +1,11 @@
+.. _trio-resolver-class:
+
+The dns.trio.resolver.Resolver Class
+------------------------------------
+
+The Trio resolver is a subclass of ``dns.resolver.Resolver`` and has the
+same attributes.  The methods are similar, but I/O methods like ``resolve()``
+are asynchronous.
+
+.. autoclass:: dns.trio.resolver.Resolver
+   :members:

diff --git a/doc/trio-resolver-functions.rst b/doc/trio-resolver-functions.rst
new file mode 100644 (file)
index 0000000..2a6ab31
--- /dev/null
+++ b/doc/trio-resolver-functions.rst
@@ -0,0 +1,8 @@
+.. _trio-resolver-functions:
+
+Trio Resolver Functions
+=======================
+
+.. autofunction:: dns.trio.resolver.resolve
+.. autofunction:: dns.trio.resolver.resolve_address
+.. autofunction:: dns.trio.resolver.zone_for_name

diff --git a/doc/trio-resolver.rst b/doc/trio-resolver.rst
new file mode 100644 (file)
index 0000000..ccd7824
--- /dev/null
+++ b/doc/trio-resolver.rst
@@ -0,0 +1,12 @@
+.. module:: dns.trio.resolver
+.. _trio_resolver:
+
+Stub Resolver
+=============
+
+Dnspython's Trio resolver module implements an asynchronous "stub resolver".
+
+.. toctree::
+
+   trio-resolver-class
+   trio-resolver-functions

diff --git a/doc/trio.rst b/doc/trio.rst
new file mode 100644 (file)
index 0000000..3afad5f
--- /dev/null
+++ b/doc/trio.rst
@@ -0,0 +1,20 @@
+.. module:: dns.trio
+.. _trio:
+
+Trio Asynchronous I/O Support
+=============================
+
+The ``dns.trio.query`` module offers very similar APIs to those of
+``dns.query``, only these versions are asynchronous and use Trio for
+I/O.  There are no timeout parameters, as timeouts are expected to be
+done in the Trio style with a cancellation scope.
+
+The ``dns.trio.resolver`` module offers very similar APIs to those of
+``dns.query``, only these versions are asynchronous and use Trio for
+I/O.  There are no timeout parameters, as timeouts are expected to be
+done in the Trio style with a cancellation scope.
+
+.. toctree::
+
+   trio-query
+   trio-resolver