https://github.com/python/cpython/commit/1d17f1a979e463d7c9e56cb9bb9aeab1b4b6aec7
commit: 1d17f1a979e463d7c9e56cb9bb9aeab1b4b6aec7
branch: 3.12
author: Miss Islington (bot) <31488909+miss-isling...@users.noreply.github.com>
committer: picnixz <10796600+picn...@users.noreply.github.com>
date: 2025-03-16T12:00:39Z
summary:
[3.12] gh-130160: use `.. program::` directive for documenting `doctest` CLI
(GH-131034) (#131321)
gh-130160: use `.. program::` directive for documenting `doctest` CLI
(GH-131034)
(cherry picked from commit 9558d22ac308c102e4f843541eead2022050225e)
Co-authored-by: donBarbos <donbar...@proton.me>
Co-authored-by: Bénédikt Tran <10796600+picn...@users.noreply.github.com>
files:
M Doc/library/cmdline.rst
M Doc/library/doctest.rst
diff --git a/Doc/library/cmdline.rst b/Doc/library/cmdline.rst
index b2379befeffcba..77d095cb0884e1 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`
+* :ref:`doctest <doctest-cli>`
* :mod:`!encodings.rot_13`
* :mod:`ensurepip`
* :mod:`filecmp`
diff --git a/Doc/library/doctest.rst b/Doc/library/doctest.rst
index 423108bf7fc1c7..f63ec272b6d880 100644
--- a/Doc/library/doctest.rst
+++ b/Doc/library/doctest.rst
@@ -173,15 +173,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`.
@@ -244,16 +237,53 @@ 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` instead::
+
+ 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:
@@ -536,9 +566,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:
@@ -678,11 +705,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
_______________________________________________
Python-checkins mailing list -- python-checkins@python.org
To unsubscribe send an email to python-checkins-le...@python.org
https://mail.python.org/mailman3/lists/python-checkins.python.org/
Member address: arch...@mail-archive.com
