docs: Add sphinx coverage check to docs tox build

docs/conf.py

@@ -36,7 +36,9 @@ autodoc_inherit_docstrings = False
 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",
@@ -106,6 +108,7 @@ missing_references = {
     "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/testing.rst

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

tornado/testing.py

@@ -754,7 +754,17 @@ class ExpectLog(logging.Filter):
 
 # From https://nedbatchelder.com/blog/201508/using_context_managers_in_test_setup.html
 def setup_with_context_manager(testcase: unittest.TestCase, cm: Any) -> Any:
-    """Use a contextmanager to setUp a test case."""
+    """Use a context manager to setUp a test case.
+
+    Example::
+
+        def setUp(self):
+            setup_with_context_manager(self, warnings.catch_warnings())
+            warnings.filterwarnings("ignore", category=DeprecationWarning)
+            # The catch_warnings context manager will be deactivated
+            # automatically in tearDown.
+
+    """
     val = cm.__enter__()
     testcase.addCleanup(cm.__exit__, None, None, None)
     return val

tox.ini

@@ -101,6 +101,8 @@ setenv = TORNADO_EXTENSION=0
 commands =
     # Build the docs
     sphinx-build -q -E -n -W -b html . {envtmpdir}/html
+    # Ensure that everything is either documented or ignored in conf.py
+    sphinx-build -q -E -n -W -b coverage . {envtmpdir}/coverage
     # Run the doctests. No -W for doctests because that disallows tests
     # with empty output.
     sphinx-build -q -E -n -b doctest . {envtmpdir}/doctest