From 805ce5838351a1f45b4c369d41bc92dc34356191 Mon Sep 17 00:00:00 2001
From: donBarbos <donbarbos@proton.me>
Date: Mon, 10 Mar 2025 13:14:58 +0400
Subject: [PATCH 1/3] use `.. program::` directive for documenting `doctest`
 CLI

---
 Doc/library/cmdline.rst |  2 +-
 Doc/library/doctest.rst | 69 +++++++++++++++++++++++++++--------------
 2 files changed, 46 insertions(+), 25 deletions(-)

diff --git a/Doc/library/cmdline.rst b/Doc/library/cmdline.rst
index 78fe95a014ff7c..bc251771d81940 100644
--- a/Doc/library/cmdline.rst
+++ b/Doc/library/cmdline.rst
@@ -13,7 +13,7 @@ The following modules have a command-line interface.
 * :mod:`cProfile`: see :ref:`profile <profile-cli>`
 * :ref:`difflib <difflib-interface>`
 * :ref:`dis <dis-cli>`
-* :mod:`doctest`
+* :mod:`doctest <doctest-cli>`
 * :mod:`!encodings.rot_13`
 * :mod:`ensurepip`
 * :mod:`filecmp`
diff --git a/Doc/library/doctest.rst b/Doc/library/doctest.rst
index 106b0a6c95b7be..22a5b22d992abf 100644
--- a/Doc/library/doctest.rst
+++ b/Doc/library/doctest.rst
@@ -177,15 +177,8 @@ prohibit it by passing ``verbose=False``.  In either of those cases,
 ``sys.argv`` is not examined by :func:`testmod` (so passing ``-v`` or not
 has no effect).
 
-There is also a command line shortcut for running :func:`testmod`.  You can
-instruct the Python interpreter to run the doctest module directly from the
-standard library and pass the module name(s) on the command line::
-
-   python -m doctest -v example.py
-
-This will import :file:`example.py` as a standalone module and run
-:func:`testmod` on it.  Note that this may not work correctly if the file is
-part of a package and imports other submodules from that package.
+There is also a command line shortcut for running :func:`testmod`, see section
+:ref:`doctest-cli`.
 
 For more information on :func:`testmod`, see section :ref:`doctest-basic-api`.
 
@@ -248,16 +241,52 @@ Like :func:`testmod`, :func:`testfile`'s verbosity can be set with the
 ``-v`` command-line switch or with the optional keyword argument
 *verbose*.
 
-There is also a command line shortcut for running :func:`testfile`.  You can
-instruct the Python interpreter to run the doctest module directly from the
-standard library and pass the file name(s) on the command line::
+There is also a command line shortcut for running :func:`testfile`, see section
+:ref:`doctest-cli`.
 
-   python -m doctest -v example.txt
+For more information on :func:`testfile`, see section :ref:`doctest-basic-api`.
 
-Because the file name does not end with :file:`.py`, :mod:`doctest` infers that
-it must be run with :func:`testfile`, not :func:`testmod`.
 
-For more information on :func:`testfile`, see section :ref:`doctest-basic-api`.
+.. _doctest-cli:
+
+Command-line Usage
+------------------
+
+The :mod:`doctest` module can be invoked as a script from the command line:
+
+.. code-block:: bash
+
+   python -m doctest [-v] [-o OPTION] [-f] file [file ...]
+
+.. program:: doctest
+
+.. option:: -v, --verbose
+
+   Detailed report of all examples tried is printed to standard output,
+   along with assorted summaries at the end::
+
+      python -m doctest -v example.py
+
+   This will import :file:`example.py` as a standalone module and run
+   :func:`testmod` on it.  Note that this may not work correctly if the file is
+   part of a package and imports other submodules from that package.
+   If the file name does not end with :file:`.py`, :mod:`doctest` infers that
+   it must be run with :func:`testfile`, not :func:`testmod`::
+
+      python -m doctest -v example.txt
+
+.. option:: -o, --option <option>
+
+   Option flags control various aspects of doctest's behavior, see section
+   :ref:`doctest-options`.
+
+   .. versionadded:: 3.4
+
+.. option:: -f, --fail-fast
+
+   This is shorthand for ``-o FAIL_FAST``.
+
+   .. versionadded:: 3.4
 
 
 .. _doctest-how-it-works:
@@ -540,9 +569,6 @@ Symbolic names for the flags are supplied as module constants, which can be
 The names can also be used in :ref:`doctest directives <doctest-directives>`,
 and may be passed to the doctest command line interface via the ``-o`` option.
 
-.. versionadded:: 3.4
-   The ``-o`` command line option.
-
 The first group of options define test semantics, controlling aspects of how
 doctest decides whether actual output matches an example's expected output:
 
@@ -682,11 +708,6 @@ The second group of options controls how test failures are reported:
    1.  This flag may be useful during debugging, since examples after the first
    failure won't even produce debugging output.
 
-   The doctest command line accepts the option ``-f`` as a shorthand for ``-o
-   FAIL_FAST``.
-
-   .. versionadded:: 3.4
-
 
 .. data:: REPORTING_FLAGS
 

From 56c2b7cfebb08f8a1b28025f65b564d88804c76f Mon Sep 17 00:00:00 2001
From: donBarbos <donbarbos@proton.me>
Date: Mon, 10 Mar 2025 13:29:56 +0400
Subject: [PATCH 2/3] Correct ref syntax

---
 Doc/library/cmdline.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Doc/library/cmdline.rst b/Doc/library/cmdline.rst
index bc251771d81940..7ef9bdb498c398 100644
--- a/Doc/library/cmdline.rst
+++ b/Doc/library/cmdline.rst
@@ -13,7 +13,7 @@ The following modules have a command-line interface.
 * :mod:`cProfile`: see :ref:`profile <profile-cli>`
 * :ref:`difflib <difflib-interface>`
 * :ref:`dis <dis-cli>`
-* :mod:`doctest <doctest-cli>`
+* :ref:`doctest <doctest-cli>`
 * :mod:`!encodings.rot_13`
 * :mod:`ensurepip`
 * :mod:`filecmp`

From a5c8c5954d124e121768696d546ef648513545c7 Mon Sep 17 00:00:00 2001
From: donBarbos <donbarbos@proton.me>
Date: Sun, 16 Mar 2025 15:47:52 +0400
Subject: [PATCH 3/3] Update doctest.rst
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-authored-by: Bénédikt Tran <10796600+picnixz@users.noreply.github.com>
---
 Doc/library/doctest.rst | 9 +++++----
 1 file changed, 5 insertions(+), 4 deletions(-)

diff --git a/Doc/library/doctest.rst b/Doc/library/doctest.rst
index 22a5b22d992abf..b86fef9fd6f310 100644
--- a/Doc/library/doctest.rst
+++ b/Doc/library/doctest.rst
@@ -268,10 +268,11 @@ The :mod:`doctest` module can be invoked as a script from the command line:
       python -m doctest -v example.py
 
    This will import :file:`example.py` as a standalone module and run
-   :func:`testmod` on it.  Note that this may not work correctly if the file is
-   part of a package and imports other submodules from that package.
-   If the file name does not end with :file:`.py`, :mod:`doctest` infers that
-   it must be run with :func:`testfile`, not :func:`testmod`::
+   :func:`testmod` on it. Note that this may not work correctly if the
+   file is part of a package and imports other submodules from that package.
+
+   If the file name does not end with :file:`.py`, :mod:`!doctest` infers
+   that it must be run with :func:`testfile` instead::
 
       python -m doctest -v example.txt