Merge pull request python-trio#1091 from bengartner/sphinx-default-role

Refactor to default role obj

Author: njsmith

docs/source/conf.py

@@ -39,6 +39,7 @@
     ("py:exc", "Anything else"),
 ]
 autodoc_inherit_docstrings = False
+default_role = "obj"
 
 # XX hack the RTD theme until
 #   https://github.com/rtfd/sphinx_rtd_theme/pull/382

docs/source/history.rst

@@ -109,7 +109,7 @@ Features
   also reexports all the stdlib :mod:`subprocess` exceptions and constants for
   convenience. (`#4 <https://github.com/python-trio/trio/issues/4>`__)
 - You can now create an unbounded :class:`CapacityLimiter` by initializing with
-  :obj:`math.inf` (`#618 <https://github.com/python-trio/trio/issues/618>`__)
+  `math.inf` (`#618 <https://github.com/python-trio/trio/issues/618>`__)
 - New :mod:`trio.hazmat` features to allow cleanly switching live coroutine
   objects between Trio and other coroutine runners. Frankly, we're not even
   sure this is a good idea, but we want to `try it out in trio-asyncio
@@ -238,7 +238,7 @@ Bugfixes
 - Prevent crashes when used with Sentry (raven-python). (`#599
   <https://github.com/python-trio/trio/issues/599>`__)
 - The nursery context manager was rewritten to avoid use of
-  `@asynccontextmanager` and `@async_generator`. This reduces extraneous frames
+  ``@asynccontextmanager`` and ``@async_generator``. This reduces extraneous frames
   in exception traces and addresses bugs regarding `StopIteration` and
   `StopAsyncIteration` exceptions not propagating correctly. (`#612
   <https://github.com/python-trio/trio/issues/612>`__)

docs/source/reference-core.rst

@@ -706,7 +706,7 @@ in Python there can only be one exception at a time.
 Trio's answer is that it raises a :exc:`MultiError` object. This is a
 special exception which encapsulates multiple exception objects –
 either regular exceptions or nested :exc:`MultiError`\s. To make these
-easier to work with, Trio installs a custom :obj:`sys.excepthook` that
+easier to work with, Trio installs a custom `sys.excepthook` that
 knows how to print nice tracebacks for unhandled :exc:`MultiError`\s,
 and it also provides some helpful utilities like
 :meth:`MultiError.catch`, which allows you to catch "part of" a

trio/_file_io.py

@@ -181,7 +181,7 @@ def wrap_file(file):
         file: a :term:`file object`
 
     Returns:
-        An :term:`asynchronous file object` that wraps `file`
+        An :term:`asynchronous file object` that wraps ``file``
 
     Example::
 

trio/_highlevel_open_tcp_stream.py

@@ -210,7 +210,7 @@ async def open_tcp_stream(
       port (int): The port to connect to.
       happy_eyeballs_delay (float): How many seconds to wait for each
           connection attempt to succeed or fail before getting impatient and
-          starting another one in parallel. Set to :obj:`math.inf` if you want
+          starting another one in parallel. Set to `math.inf` if you want
           to limit to only one connection attempt at a time (like
           :func:`socket.create_connection`). Default: 0.3 (300 ms).
 

trio/_ssl.py

@@ -298,7 +298,7 @@ class SSLStream(Stream):
     raises :exc:`NeedHandshakeError`.
 
     This also means that if you register a SNI callback using
-    :obj:`~ssl.SSLContext.sni_callback`, then the first argument your callback
+    `~ssl.SSLContext.sni_callback`, then the first argument your callback
     receives will be a :class:`ssl.SSLObject`.
 
     """