pythongh-134918: Fix and improve doctest's documentation (pythonGH-134919)

Author: serhiy-storchaka

Doc/library/doctest.rst

@@ -174,7 +174,7 @@ with assorted summaries at the end.
 
 You can force verbose mode by passing ``verbose=True`` to :func:`testmod`, or
 prohibit it by passing ``verbose=False``.  In either of those cases,
-``sys.argv`` is not examined by :func:`testmod` (so passing ``-v`` or not
+:data:`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`, see section
@@ -231,7 +231,7 @@ documentation::
 As with :func:`testmod`, :func:`testfile` won't display anything unless an
 example fails.  If an example does fail, then the failing example(s) and the
 cause(s) of the failure(s) are printed to stdout, using the same format as
-:func:`testmod`.
+:func:`!testmod`.
 
 By default, :func:`testfile` looks for files in the calling module's directory.
 See section :ref:`doctest-basic-api` for a description of the optional arguments
@@ -311,6 +311,9 @@ Which Docstrings Are Examined?
 The module docstring, and all function, class and method docstrings are
 searched.  Objects imported into the module are not searched.
 
+.. attribute:: module.__test__
+   :no-typesetting:
+
 In addition, there are cases when you want tests to be part of a module but not part
 of the help text, which requires that the tests not be included in the docstring.
 Doctest looks for a module-level variable called ``__test__`` and uses it to locate other
@@ -533,7 +536,7 @@ Some details you should read once, but won't need to remember:
 * The interactive shell omits the traceback header line for some
   :exc:`SyntaxError`\ s.  But doctest uses the traceback header line to
   distinguish exceptions from non-exceptions.  So in the rare case where you need
-  to test a :exc:`SyntaxError` that omits the traceback header, you will need to
+  to test a :exc:`!SyntaxError` that omits the traceback header, you will need to
   manually add the traceback header line to your test example.
 
 .. index:: single: ^ (caret); marker
@@ -860,15 +863,15 @@ The :const:`ELLIPSIS` directive gives a nice approach for the last example:
    <C object at 0x...>
 
 Floating-point numbers are also subject to small output variations across
-platforms, because Python defers to the platform C library for float formatting,
-and C libraries vary widely in quality here. ::
+platforms, because Python defers to the platform C library for some
+floating-point calculations, and C libraries vary widely in quality here. ::
 
-   >>> 1./7  # risky
-   0.14285714285714285
-   >>> print(1./7) # safer
-   0.142857142857
-   >>> print(round(1./7, 6)) # much safer
-   0.142857
+   >>> 1000**0.1  # risky
+   1.9952623149688797
+   >>> round(1000**0.1, 9) # safer
+   1.995262315
+   >>> print(f'{1000**0.1:.4f}') # much safer
+   1.9953
 
 Numbers of the form ``I/2.**J`` are safe across all platforms, and I often
 contrive doctest examples to produce numbers of that form::
@@ -938,13 +941,13 @@ and :ref:`doctest-simple-testfile`.
 
    Optional argument *verbose* prints lots of stuff if true, and prints only
    failures if false; by default, or if ``None``, it's true if and only if ``'-v'``
-   is in ``sys.argv``.
+   is in :data:`sys.argv`.
 
    Optional argument *report* prints a summary at the end when true, else prints
    nothing at the end.  In verbose mode, the summary is detailed, else the summary
    is very brief (in fact, empty if all tests passed).
 
-   Optional argument *optionflags* (default value 0) takes the
+   Optional argument *optionflags* (default value ``0``) takes the
    :ref:`bitwise OR <bitwise>` of option flags.
    See section :ref:`doctest-options`.
 
@@ -1045,7 +1048,7 @@ from text files and modules with doctests:
 
    The returned :class:`unittest.TestSuite` is to be run by the unittest framework
    and runs the interactive examples in each file.  If an example in any file
-   fails, then the synthesized unit test fails, and a :exc:`failureException`
+   fails, then the synthesized unit test fails, and a :exc:`~unittest.TestCase.failureException`
    exception is raised showing the name of the file containing the test and a
    (sometimes approximate) line number.  If all the examples in a file are
    skipped, then the synthesized unit test is also marked as skipped.
@@ -1078,13 +1081,14 @@ from text files and modules with doctests:
 
    Optional argument *setUp* specifies a set-up function for the test suite.
    This is called before running the tests in each file.  The *setUp* function
-   will be passed a :class:`DocTest` object.  The setUp function can access the
-   test globals as the *globs* attribute of the test passed.
+   will be passed a :class:`DocTest` object.  The *setUp* function can access the
+   test globals as the :attr:`~DocTest.globs` attribute of the test passed.
 
    Optional argument *tearDown* specifies a tear-down function for the test
    suite.  This is called after running the tests in each file.  The *tearDown*
-   function will be passed a :class:`DocTest` object.  The setUp function can
-   access the test globals as the *globs* attribute of the test passed.
+   function will be passed a :class:`DocTest` object.  The *tearDown* function can
+   access the test globals as the :attr:`~DocTest.globs` attribute of the test
+   passed.
 
    Optional argument *globs* is a dictionary containing the initial global
    variables for the tests.  A new copy of this dictionary is created for each
@@ -1111,19 +1115,20 @@ from text files and modules with doctests:
    Convert doctest tests for a module to a :class:`unittest.TestSuite`.
 
    The returned :class:`unittest.TestSuite` is to be run by the unittest framework
-   and runs each doctest in the module.  If any of the doctests fail, then the
-   synthesized unit test fails, and a :exc:`failureException` exception is raised
+   and runs each doctest in the module.
+   Each docstring is run as a separate unit test.
+   If any of the doctests fail, then the synthesized unit test fails,
+   and a :exc:`unittest.TestCase.failureException` exception is raised
    showing the name of the file containing the test and a (sometimes approximate)
    line number.  If all the examples in a docstring are skipped, then the
-   synthesized unit test is also marked as skipped.
 
    Optional argument *module* provides the module to be tested.  It can be a module
    object or a (possibly dotted) module name.  If not specified, the module calling
    this function is used.
 
    Optional argument *globs* is a dictionary containing the initial global
    variables for the tests.  A new copy of this dictionary is created for each
-   test.  By default, *globs* is a new empty dictionary.
+   test.  By default, *globs* is the module's :attr:`~module.__dict__`.
 
    Optional argument *extraglobs* specifies an extra set of global variables, which
    is merged into *globs*.  By default, no extra globals are used.
@@ -1132,20 +1137,14 @@ from text files and modules with doctests:
    drop-in replacement) that is used to extract doctests from the module.
 
    Optional arguments *setUp*, *tearDown*, and *optionflags* are the same as for
-   function :func:`DocFileSuite` above.
+   function :func:`DocFileSuite` above, but they are called for each docstring.
 
    This function uses the same search technique as :func:`testmod`.
 
    .. versionchanged:: 3.5
       :func:`DocTestSuite` returns an empty :class:`unittest.TestSuite` if *module*
       contains no docstrings instead of raising :exc:`ValueError`.
 
-.. exception:: failureException
-
-   When doctests which have been converted to unit tests by :func:`DocFileSuite`
-   or :func:`DocTestSuite` fail, this exception is raised showing the name of
-   the file containing the test and a (sometimes approximate) line number.
-
 Under the covers, :func:`DocTestSuite` creates a :class:`unittest.TestSuite` out
 of :class:`!doctest.DocTestCase` instances, and :class:`!DocTestCase` is a
 subclass of :class:`unittest.TestCase`. :class:`!DocTestCase` isn't documented
@@ -1158,15 +1157,15 @@ of :class:`!DocTestCase`.
 
 So both ways of creating a :class:`unittest.TestSuite` run instances of
 :class:`!DocTestCase`.  This is important for a subtle reason: when you run
-:mod:`doctest` functions yourself, you can control the :mod:`doctest` options in
-use directly, by passing option flags to :mod:`doctest` functions.  However, if
-you're writing a :mod:`unittest` framework, :mod:`unittest` ultimately controls
+:mod:`doctest` functions yourself, you can control the :mod:`!doctest` options in
+use directly, by passing option flags to :mod:`!doctest` functions.  However, if
+you're writing a :mod:`unittest` framework, :mod:`!unittest` ultimately controls
 when and how tests get run.  The framework author typically wants to control
-:mod:`doctest` reporting options (perhaps, e.g., specified by command line
-options), but there's no way to pass options through :mod:`unittest` to
-:mod:`doctest` test runners.
+:mod:`!doctest` reporting options (perhaps, e.g., specified by command line
+options), but there's no way to pass options through :mod:`!unittest` to
+:mod:`!doctest` test runners.
 
-For this reason, :mod:`doctest` also supports a notion of :mod:`doctest`
+For this reason, :mod:`doctest` also supports a notion of :mod:`!doctest`
 reporting flags specific to :mod:`unittest` support, via this function:
 
 
@@ -1181,12 +1180,12 @@ reporting flags specific to :mod:`unittest` support, via this function:
    :mod:`unittest`:  the :meth:`!runTest` method of :class:`!DocTestCase` looks at
    the option flags specified for the test case when the :class:`!DocTestCase`
    instance was constructed.  If no reporting flags were specified (which is the
-   typical and expected case), :mod:`!doctest`'s :mod:`unittest` reporting flags are
+   typical and expected case), :mod:`!doctest`'s :mod:`!unittest` reporting flags are
    :ref:`bitwise ORed <bitwise>` into the option flags, and the option flags
    so augmented are passed to the :class:`DocTestRunner` instance created to
    run the doctest.  If any reporting flags were specified when the
    :class:`!DocTestCase` instance was constructed, :mod:`!doctest`'s
-   :mod:`unittest` reporting flags are ignored.
+   :mod:`!unittest` reporting flags are ignored.
 
    The value of the :mod:`unittest` reporting flags in effect before the function
    was called is returned by the function.
@@ -1279,7 +1278,7 @@ DocTest Objects
    .. attribute:: filename
 
       The name of the file that this :class:`DocTest` was extracted from; or
-      ``None`` if the filename is unknown, or if the :class:`DocTest` was not
+      ``None`` if the filename is unknown, or if the :class:`!DocTest` was not
       extracted from a file.
 
 
@@ -1419,10 +1418,10 @@ DocTestFinder objects
 
       The globals for each :class:`DocTest` is formed by combining *globs* and
       *extraglobs* (bindings in *extraglobs* override bindings in *globs*).  A new
-      shallow copy of the globals dictionary is created for each :class:`DocTest`.
-      If *globs* is not specified, then it defaults to the module's *__dict__*, if
-      specified, or ``{}`` otherwise.  If *extraglobs* is not specified, then it
-      defaults to ``{}``.
+      shallow copy of the globals dictionary is created for each :class:`!DocTest`.
+      If *globs* is not specified, then it defaults to the module's
+      :attr:`~module.__dict__`, if specified, or ``{}`` otherwise.
+      If *extraglobs* is not specified, then it defaults to ``{}``.
 
 
 .. _doctest-doctestparser:
@@ -1446,7 +1445,7 @@ DocTestParser objects
       :class:`DocTest` object.
 
       *globs*, *name*, *filename*, and *lineno* are attributes for the new
-      :class:`DocTest` object.  See the documentation for :class:`DocTest` for more
+      :class:`!DocTest` object.  See the documentation for :class:`DocTest` for more
       information.
 
 
@@ -1461,7 +1460,7 @@ DocTestParser objects
 
       Divide the given string into examples and intervening text, and return them as
       a list of alternating :class:`Example`\ s and strings. Line numbers for the
-      :class:`Example`\ s are 0-based.  The optional argument *name* is a name
+      :class:`!Example`\ s are 0-based.  The optional argument *name* is a name
       identifying this string, and is only used for error messages.
 
 
@@ -1501,7 +1500,7 @@ DocTestRunner objects
    :class:`OutputChecker`.  This comparison may be customized with a number of
    option flags; see section :ref:`doctest-options` for more information.  If the
    option flags are insufficient, then the comparison may also be customized by
-   passing a subclass of :class:`OutputChecker` to the constructor.
+   passing a subclass of :class:`!OutputChecker` to the constructor.
 
    The test runner's display output can be controlled in two ways. First, an output
    function can be passed to :meth:`run`; this function will be called
@@ -1540,7 +1539,7 @@ DocTestRunner objects
       output; it should not be called directly.
 
       *example* is the example about to be processed.  *test* is the test
-      *containing example*.  *out* is the output function that was passed to
+      containing *example*.  *out* is the output function that was passed to
       :meth:`DocTestRunner.run`.
 
 
@@ -1940,7 +1939,7 @@ several options for organizing tests:
   containing test cases for the named topics.  These functions can be included in
   the same file as the module, or separated out into a separate test file.
 
-* Define a ``__test__`` dictionary mapping from regression test topics to
+* Define a :attr:`~module.__test__` dictionary mapping from regression test topics to
   docstrings containing test cases.
 
 When you have placed your tests in a module, the module can itself be the test