Skip to content

[3.13] gh-130160: use .. program:: directive for documenting doctest CLI (GH-131034) #131320

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Mar 16, 2025
Merged

[3.13] gh-130160: use .. program:: directive for documenting doctest CLI (GH-131034) #131320

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion Doc/library/cmdline.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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`
Expand Down
70 changes: 46 additions & 24 deletions Doc/library/doctest.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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`.

Expand Down Expand Up @@ -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:
Expand Down Expand Up @@ -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:

Expand Down Expand Up @@ -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

Expand Down
Loading