From f07862cfc5afce5dd094f7df23b064dd8fbc9d1f Mon Sep 17 00:00:00 2001 From: bswck Date: Sun, 17 Aug 2025 03:32:47 +0200 Subject: [PATCH 1/5] Add a warning about nested classes and functions --- Doc/library/doctest.rst | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/Doc/library/doctest.rst b/Doc/library/doctest.rst index 5a2c6bdd27c386..fbddff7057e172 100644 --- a/Doc/library/doctest.rst +++ b/Doc/library/doctest.rst @@ -350,6 +350,15 @@ searches them recursively for docstrings, which are then scanned for tests. Any classes found are recursively searched similarly, to test docstrings in their contained methods and nested classes. +.. warning:: + + Only classes and functions defined at the module level (or inside other + classes) are automatically discovered by ``doctest``. + + Classes or functions defined inside functions cannot be discovered, + because their definitions depend on the runtime state of the enclosing + function. To make their doctests discoverable, define them outside of + the enclosing function. .. _doctest-finding-examples: From 25efc3875a09dacfe6f1cb28b7d02f48c121af94 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bartosz=20S=C5=82awecki?= Date: Sun, 17 Aug 2025 16:10:25 +0200 Subject: [PATCH 2/5] Use note admonition instead of warning --- Doc/library/doctest.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/doctest.rst b/Doc/library/doctest.rst index fbddff7057e172..66d82497e81c52 100644 --- a/Doc/library/doctest.rst +++ b/Doc/library/doctest.rst @@ -350,7 +350,7 @@ searches them recursively for docstrings, which are then scanned for tests. Any classes found are recursively searched similarly, to test docstrings in their contained methods and nested classes. -.. warning:: +.. note:: Only classes and functions defined at the module level (or inside other classes) are automatically discovered by ``doctest``. From 20fc71a36a972ad604c08fb9af36f56d2e15e6da Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bartosz=20S=C5=82awecki?= Date: Mon, 18 Aug 2025 00:53:09 +0200 Subject: [PATCH 3/5] Review 1 Co-authored-by: Peter Bierma --- Doc/library/doctest.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/doctest.rst b/Doc/library/doctest.rst index 66d82497e81c52..e6909f111f8b8e 100644 --- a/Doc/library/doctest.rst +++ b/Doc/library/doctest.rst @@ -357,7 +357,7 @@ their contained methods and nested classes. Classes or functions defined inside functions cannot be discovered, because their definitions depend on the runtime state of the enclosing - function. To make their doctests discoverable, define them outside of + function. To make them discoverable, define them outside of the enclosing function. .. _doctest-finding-examples: From 479eeae03d02068d383d6f2eea6e5587217bc692 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bartosz=20S=C5=82awecki?= Date: Mon, 18 Aug 2025 00:53:44 +0200 Subject: [PATCH 4/5] Review 2 --- Doc/library/doctest.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/doctest.rst b/Doc/library/doctest.rst index e6909f111f8b8e..a37c44c4d18915 100644 --- a/Doc/library/doctest.rst +++ b/Doc/library/doctest.rst @@ -356,7 +356,7 @@ their contained methods and nested classes. classes) are automatically discovered by ``doctest``. Classes or functions defined inside functions cannot be discovered, - because their definitions depend on the runtime state of the enclosing + because their definitions depend on the state of the enclosing function. To make them discoverable, define them outside of the enclosing function. From 54cebea677eea2a88a34f8f46946550ec1337c11 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bartosz=20S=C5=82awecki?= Date: Mon, 18 Aug 2025 06:32:12 +0200 Subject: [PATCH 5/5] Use clearer language --- Doc/library/doctest.rst | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) diff --git a/Doc/library/doctest.rst b/Doc/library/doctest.rst index a37c44c4d18915..02b73ccd3f3d19 100644 --- a/Doc/library/doctest.rst +++ b/Doc/library/doctest.rst @@ -352,13 +352,11 @@ their contained methods and nested classes. .. note:: - Only classes and functions defined at the module level (or inside other - classes) are automatically discovered by ``doctest``. + ``doctest`` can only automatically discover classes and functions that are + defined at the module level or inside other classes. - Classes or functions defined inside functions cannot be discovered, - because their definitions depend on the state of the enclosing - function. To make them discoverable, define them outside of - the enclosing function. + Since nested classes and functions only exist when an outer function + is called, they cannot be discovered. Define them outside to make them visible. .. _doctest-finding-examples: