fix documentation

single- vs. double-colon annoyances

Author: smurfix

docs/source/conf.py

@@ -30,23 +30,6 @@
     ("py:class", "CapacityLimiter-like object"),
     ("py:class", "bytes-like"),
     ("py:class", "None"),
-    ("py:func", "trio_asyncio.wait_for_child"),
-    ("py:func", "trio_asyncio.run_future"),
-    ("py:func", "trio_asyncio.run_coroutine"),
-    ("py:func", "trio_asyncio.run_asyncio"),
-    ("py:func", "trio_asyncio.aio_as_trio"),
-    ("py:func", "trio_asyncio.trio_as_aio"),
-    ("py:func", "trio_asyncio.allow_asyncio"),
-    ("py:func", "sniffio.current_async_library"),
-    ("py:class", "trio_asyncio.TrioEventLoop"),
-    ("py:class", "trio_asyncio.TrioExecutor"),
-    ("py:class", "trio_asyncio.TrioChildWatcher"),
-    ("py:meth", "trio_asyncio.TrioEventLoop.autoclose"),
-    ("py:meth", "trio_asyncio.TrioEventLoop.add_reader"),
-    ("py:meth", "trio_asyncio.TrioEventLoop.add_writer"),
-    ("py:meth", "trio_asyncio.TrioEventLoop.run_trio_task"),
-    ("py:meth", "trio_asyncio.sync.SyncTrioEventLoop.run_until_complete"),
-    ("py:mod", "trio_asyncio"), ## ???
 ]
 
 autodoc_inherit_docstrings = False
@@ -71,7 +54,7 @@
 intersphinx_mapping = {
     "python": ('https://docs.python.org/3', None),
     "trio": ('https://trio.readthedocs.io/en/stable', None),
-    # "sniffio": ('https://sniffio.readthedocs.io/en/stable', None),
+    "sniffio": ('https://sniffio.readthedocs.io/en/latest', None),
 }
 
 autodoc_member_order = "bysource"

docs/source/usage.rst

@@ -3,7 +3,7 @@
  Usage
 +++++++
 
-.. module: trio_asyncio
+.. module:: trio_asyncio
 
 Using :mod:`trio` from :mod:`asyncio`, or vice versa, requires two steps:
 
@@ -74,6 +74,8 @@ the loop's context.
 
 .. autofunction:: trio_asyncio.run
 
+.. autoclass:: trio_asyncio.TrioEventLoop
+
 .. note:
 
    The ``async with open_loop()`` way of running ``trio_asyncio`` is
@@ -349,7 +351,7 @@ to wrap the iterator, not the code creating it – the following code
         async for n in aio_as_trio(aio_slow)():
             print(n)
 
-.. autodoc: trio_asyncio.aio_as_trio
+.. autofunction:: trio_asyncio.aio_as_trio
 
 
 Too complicated?
@@ -375,7 +377,7 @@ code to Trio callers, but not vice versa.
 
 Thus, you really should not use it for "real" programs or libraries.
 
-.. autodoc: trio_asyncio.allow_asyncio
+.. autofunction:: trio_asyncio.allow_asyncio
 
 Calling Trio from asyncio
 +++++++++++++++++++++++++
@@ -450,7 +452,7 @@ You can also wrap async generators or iterators::
             print(n)
     trio_asyncio.run(aio_as_trio, printer)
 
-.. autodoc: trio_asyncio.trio_as_aio
+.. autofunction:: trio_as_aio
 
 
 Trio background tasks
@@ -461,7 +463,7 @@ If you want to start a Trio task that shall be monitored by ``trio_asyncio``
 loop) instead of a :class:`asyncio.Future`, use
 :meth:`trio_asyncio.TrioEventLoop.run_trio_task`.
 
-.. autodoc: trio_asyncio.TrioEventLoop.run_trio_task
+.. automethod:: trio_asyncio.TrioEventLoop.run_trio_task
 
 Multiple asyncio loops
 ++++++++++++++++++++++
@@ -482,7 +484,13 @@ method is mainly useful for servers and should be used as supplementing,
 but not replacing, a ``finally:`` handler or an ``async with aclosing():``
 block.
 
-.. autodoc: trio_asyncio.TrioEventLoop.autoclose
+.. automethod:: trio_asyncio.TrioEventLoop.autoclose
+
+.. automethod:: trio_asyncio.TrioEventLoop.add_reader
+.. automethod:: trio_asyncio.TrioEventLoop.remove_reader
+
+.. automethod:: trio_asyncio.TrioEventLoop.add_writer
+.. automethod:: trio_asyncio.TrioEventLoop.remove_writer
 
 Errors and cancellations
 ++++++++++++++++++++++++
@@ -526,6 +534,8 @@ There is one caveat: the executor must be either ``None`` or an instance of
 :class:`trio_asyncio.TrioExecutor`. The constructor of this class accepts one
 argument: the number of workers.
 
+.. autoclass:: trio_asyncio.TrioExecutor
+
 ------------------
  File descriptors
 ------------------

trio_asyncio/adapter.py

@@ -105,8 +105,10 @@ def aio_as_trio(proc, *, loop=None):
     Encapsulate an asyncio-style coroutine, procedure, generator, or
     iterator, to be called seamlessly from Trio.
 
-    Note that while adapting coroutines, i.e.
+    Note that while adapting coroutines, i.e.::
+
         wrap(proc(*args))
+
     is supported (because asyncio uses them a lot) they're not a good
     idea because setting up the coroutine won't run within an asyncio
     context. If at all possible, use::
@@ -276,7 +278,7 @@ async def main():
 
     Unfortunately, there are issues with cancellation (specifically,
     :mod:`asyncio` function will see :class:`trio.Cancelled` instead of
-    :class:`asyncio.CancelledError`). Thus, this mode is not the default.
+    :exc:`concurrent.futures.CancelledError`). Thus, this mode is not the default.
 
     This function must be called from :mod:`trio` context.
     """

trio_asyncio/async_.py

@@ -11,8 +11,7 @@
 class TrioEventLoop(BaseTrioEventLoop):
     """A Trio-compatible asyncio event loop.
 
-    This loop runs in an async Trio context. If you really do need a
-    stand-alone implementation, use :class:`SyncTrioEventLoop`.
+    This loop runs in an async Trio context.
     """
 
     def _queue_handle(self, handle):

trio_asyncio/base.py

@@ -549,18 +549,16 @@ def add_reader(self, fd, callback, *args):
         ready for reading.
 
         This creates a new Trio task. You may want to use "await
-        :meth:`trio.hazmat.wait_readable`(fd) instead, or
+        :obj:`trio.hazmat.wait_readable`\ (fd)" instead, or
 
         :param fd: Either an integer (Unix file descriptor) or an object
-                   with a :meth:`fileno` methor providing one.
+                   with a ``fileno`` method providing one.
         :return: A handle. To remove the listener, either call
-                 ``handle.cancel()`` or :meth:`remove_reader`(fd).
+                 ``handle.cancel()`` or :meth:`.remove_reader`\ (fd).
         """
         self._ensure_fd_no_transport(fd)
         return self._add_reader(fd, callback, *args)
 
-    # remove_reader: unchanged from asyncio
-
     def _add_reader(self, fd, callback, *args):
         self._check_closed()
         handle = Handle(callback, args, self, context=None, is_sync=True)
@@ -604,12 +602,12 @@ def add_writer(self, fd, callback, *args):
         ready for writing.
 
         This creates a new Trio task. You may want to use "await
-        :meth:`trio.hazmat.wait_writable`(fd) instead, or
+        :obj:`trio.hazmat.wait_writable`\ (fd) instead, or
 
         :param fd: Either an integer (Unix file descriptor) or an object
-                   with a :meth:`fileno` methor providing one.
+                   with a ``fileno`` method providing one.
         :return: A handle. To remove the listener, either call
-                 ``handle.cancel()`` or :meth:`remove_writer`(fd).
+                 ``handle.cancel()`` or :meth:`remove_writer`\ (fd).
         """
         self._ensure_fd_no_transport(fd)
         return self._add_writer(fd, callback, *args)
@@ -661,7 +659,7 @@ def autoclose(self, fd):
         Calling this method twice has no effect.
 
         :param fd: Either an integer (Unix file descriptor) or an object
-                   with a :meth:`fileno` methor providing one.
+                   with a ``fileno`` method providing one.
         """
         if hasattr(fd, 'fileno'):
             fd = fd.fileno()