docs: Add sphinx coverage check to docs tox build

diff --git a/docs/conf.py b/docs/conf.py
index 661d8dce35d10804d983f339d21b85610c1c19af..bb3705873e84374a0e4c41d316f1ead963877bf6 100644 (file)
--- 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 d23ebd07b12f2a354b7f655cddda377ca4ac1317..87fd205384535876482f550dfdebe080a5c7ad30 100644 (file)
--- 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 4c33b3e22f092798ff2b70eb0940c9e9168c1dc4..4064873d487495a368a46caa46314f4aa0e00db6 100644 (file)
--- 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 78ab162b02a16fecc293965a950364e0bfeaffc3..a92c1c4c336e5110af72fe9774529a2914a50f6d 100644 (file)
--- 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