Merge pull request #3402 from bdarnell/update-sphinx

docs: Update sphinx (and the rest of the deps)

.readthedocs.yaml

@@ -3,7 +3,7 @@ version: 2
 build:
   os: ubuntu-22.04
   tools:
-    python: "3.8"
+    python: "3.11"
 
 sphinx:
   configuration: docs/conf.py

docs/conf.py

@@ -21,7 +21,6 @@
     "sphinx.ext.doctest",
     "sphinx.ext.intersphinx",
     "sphinx.ext.viewcode",
-    "sphinxcontrib.asyncio",
 ]
 
 primary_domain = "py"
@@ -37,7 +36,9 @@
 autodoc_docstring_signature = False
 
 coverage_skip_undoc_in_source = True
+coverage_show_missing_items = True
 coverage_ignore_modules = [
+    "tornado.curl_httpclient",
     "tornado.platform.asyncio",
     "tornado.platform.caresresolver",
     "tornado.platform.twisted",
@@ -107,6 +108,7 @@
     "concurrent.futures._base.Future",
     "futures.Future",
     "socket.socket",
+    "unittest.case.TestCase",
     "TextIO",
     # Other stuff. I'm not sure why some of these are showing up, but
     # I'm just listing everything here to avoid blocking the upgrade of sphinx.

docs/guide/async.rst

@@ -73,9 +73,6 @@ Here is a sample synchronous function:
         response = http_client.fetch(url)
         return response.body
 
-.. testoutput::
-   :hide:
-
 And here is the same function rewritten asynchronously as a native coroutine:
 
 .. testcode::
@@ -87,9 +84,6 @@ And here is the same function rewritten asynchronously as a native coroutine:
        response = await http_client.fetch(url)
        return response.body
 
-.. testoutput::
-   :hide:
-
 Or for compatibility with older versions of Python, using the `tornado.gen` module:
 
 ..  testcode::
@@ -118,9 +112,6 @@ Coroutines are a little magical, but what they do internally is something like t
         fetch_future.add_done_callback(on_fetch)
         return my_future
 
-.. testoutput::
-   :hide:
-
 Notice that the coroutine returns its `.Future` before the fetch is
 done. This is what makes coroutines *asynchronous*.
 

docs/guide/coroutines.rst

@@ -207,9 +207,6 @@ The `.multi` function accepts lists and dicts whose values are
                                  for url in urls})
         # responses is a dict {url: HTTPResponse}
 
-.. testoutput::
-   :hide:
-
 In decorated coroutines, it is possible to ``yield`` the list or dict directly::
 
     @gen.coroutine
@@ -238,9 +235,6 @@ immediately, so you can start another operation before waiting.
             fetch_future = convert_yielded(self.fetch_next_chunk())
             await self.flush()
 
-.. testoutput::
-   :hide:
-
 This is a little easier to do with decorated coroutines, because they
 start immediately when called:
 
@@ -256,9 +250,6 @@ start immediately when called:
             fetch_future = self.fetch_next_chunk()
             yield self.flush()
 
-.. testoutput::
-   :hide:
-
 Looping
 ^^^^^^^
 

docs/guide/running.rst

@@ -18,9 +18,6 @@ configuring a WSGI container to find your application, you write a
     if __name__ == '__main__':
         asyncio.run(main())
 
-.. testoutput::
-   :hide:
-
 Configure your operating system or process manager to run this program to
 start the server. Please note that it may be necessary to increase the number 
 of open files per process (to avoid "Too many open files"-Error). 
@@ -53,9 +50,6 @@ alterations to application startup.
             await asyncio.Event().wait()
         asyncio.run(post_fork_main())
 
-.. testoutput::
-   :hide:
-
 This is another way to start multiple processes and have them all
 share the same port, although it has some limitations.  First, each
 child process will have its own ``IOLoop``, so it is important that

docs/guide/security.rst

@@ -21,9 +21,6 @@ method:
             else:
                 self.write("Your cookie was set!")
 
-.. testoutput::
-   :hide:
-
 Cookies are not secure and can easily be modified by clients.  If you
 need to set cookies to, e.g., identify the currently logged in user,
 you need to sign your cookies to prevent forgery. Tornado supports
@@ -39,9 +36,6 @@ keyword arguments to your application:
         (r"/", MainHandler),
     ], cookie_secret="__TODO:_GENERATE_YOUR_OWN_RANDOM_VALUE_HERE__")
 
-.. testoutput::
-   :hide:
-
 Signed cookies contain the encoded value of the cookie in addition to a
 timestamp and an `HMAC <http://en.wikipedia.org/wiki/HMAC>`_ signature.
 If the cookie is old or if the signature doesn't match,
@@ -58,9 +52,6 @@ set. The secure version of the example above:
             else:
                 self.write("Your cookie was set!")
 
-.. testoutput::
-   :hide:
-
 Tornado's signed cookies guarantee integrity but not confidentiality.
 That is, the cookie cannot be modified but its contents can be seen by the
 user.  The ``cookie_secret`` is a symmetric key and must be kept secret --
@@ -129,9 +120,6 @@ specifying a nickname, which is then saved in a cookie:
         (r"/login", LoginHandler),
     ], cookie_secret="__TODO:_GENERATE_YOUR_OWN_RANDOM_VALUE_HERE__")
 
-.. testoutput::
-   :hide:
-
 You can require that the user be logged in using the `Python
 decorator <http://www.python.org/dev/peps/pep-0318/>`_
 `tornado.web.authenticated`. If a request goes to a method with this
@@ -156,9 +144,6 @@ rewritten:
         (r"/login", LoginHandler),
     ], **settings)
 
-.. testoutput::
-   :hide:
-
 If you decorate ``post()`` methods with the ``authenticated``
 decorator, and the user is not logged in, the server will send a
 ``403`` response.  The ``@authenticated`` decorator is simply
@@ -202,9 +187,6 @@ the Google credentials in a cookie for later access:
                     response_type='code',
                     extra_params={'approval_prompt': 'auto'})
 
-.. testoutput::
-   :hide:
-
 See the `tornado.auth` module documentation for more details.
 
 .. _xsrf:
@@ -237,9 +219,6 @@ include the application setting ``xsrf_cookies``:
         (r"/login", LoginHandler),
     ], **settings)
 
-.. testoutput::
-   :hide:
-
 If ``xsrf_cookies`` is set, the Tornado web application will set the
 ``_xsrf`` cookie for all users and reject all ``POST``, ``PUT``, and
 ``DELETE`` requests that do not contain a correct ``_xsrf`` value. If

docs/guide/structure.rst

@@ -37,9 +37,6 @@ A minimal "hello world" example looks something like this:
     if __name__ == "__main__":
         asyncio.run(main())
 
-.. testoutput::
-   :hide:
-
 The ``main`` coroutine
 ~~~~~~~~~~~~~~~~~~~~~~
 
@@ -153,9 +150,6 @@ and `~.RequestHandler.get_body_argument`.
             self.set_header("Content-Type", "text/plain")
             self.write("You wrote " + self.get_body_argument("message"))
 
-.. testoutput::
-   :hide:
-
 Since the HTML form encoding is ambiguous as to whether an argument is
 a single value or a list with one element, `.RequestHandler` has
 distinct methods to allow the application to indicate whether or not
@@ -332,9 +326,6 @@ For example, here is a simple handler using a coroutine:
             self.write("Fetched " + str(len(json["entries"])) + " entries "
                        "from the FriendFeed API")
 
-.. testoutput::
-   :hide:
-
 For a more advanced asynchronous example, take a look at the `chat
 example application
 <https://github.com/tornadoweb/tornado/tree/stable/demos/chat>`_, which

docs/guide/templates.rst

@@ -62,9 +62,6 @@ directory as your Python file, you could render this template with:
             items = ["Item 1", "Item 2", "Item 3"]
             self.render("template.html", title="My title", items=items)
 
-.. testoutput::
-   :hide:
-
 Tornado templates support *control statements* and *expressions*.
 Control statements are surrounded by ``{%`` and ``%}``, e.g.
 ``{% if len(items) > 2 %}``. Expressions are surrounded by ``{{`` and
@@ -202,9 +199,6 @@ by overriding `.RequestHandler.get_user_locale`:
                 return None
             return self.current_user.prefs["locale"]
 
-.. testoutput::
-   :hide:
-
 If ``get_user_locale`` returns ``None``, we fall back on the
 ``Accept-Language`` header.
 

docs/testing.rst

@@ -34,3 +34,5 @@
    .. autofunction:: bind_unused_port
 
    .. autofunction:: get_async_test_timeout
+
+   .. autofunction:: setup_with_context_manager

requirements.in

@@ -2,8 +2,7 @@ black
 flake8
 mypy>=0.941
 pip-tools
-sphinx<6
-sphinxcontrib-asyncio
+sphinx
 sphinx_rtd_theme
 types-pycurl
 tox