From 149f941af617bd48be25be3c61ba4149deed5b40 Mon Sep 17 00:00:00 2001
From: Ben Darnell <ben@bendarnell.com>
Date: Tue, 11 Jun 2024 22:01:42 -0400
Subject: [PATCH] docs: Add sphinx coverage check to docs tox build

---
 docs/conf.py       |  3 +++
 docs/testing.rst   |  2 ++
 tornado/testing.py | 12 +++++++++++-
 tox.ini            |  2 ++
 4 files changed, 18 insertions(+), 1 deletion(-)

diff --git a/docs/conf.py b/docs/conf.py
index 661d8dce..bb370587 100644
--- a/docs/conf.py
+++ b/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.
diff --git a/docs/testing.rst b/docs/testing.rst
index d23ebd07..87fd2053 100644
--- a/docs/testing.rst
+++ b/docs/testing.rst
@@ -34,3 +34,5 @@
    .. autofunction:: bind_unused_port
 
    .. autofunction:: get_async_test_timeout
+
+   .. autofunction:: setup_with_context_manager
diff --git a/tornado/testing.py b/tornado/testing.py
index 4c33b3e2..4064873d 100644
--- a/tornado/testing.py
+++ b/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
diff --git a/tox.ini b/tox.ini
index 78ab162b..a92c1c4c 100644
--- a/tox.ini
+++ b/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