DOC: Enable doctests for _config, _testing, utils, io, misc files (#44990)

* DOC: Enable doctests for _config, _testing, misc files

* Add util also

* Also fix pandas/io

* Add util to code_check

* Fix paths

Author: mroeschke

ci/code_checks.sh

@@ -66,22 +66,21 @@ if [[ -z "$CHECK" || "$CHECK" == "doctests" ]]; then
 
     MSG='Doctests' ; echo $MSG
     python -m pytest --doctest-modules \
+      pandas/_config/ \
       pandas/_libs/ \
+      pandas/_testing/ \
       pandas/api/ \
       pandas/arrays/ \
       pandas/compat/ \
       pandas/core \
       pandas/errors/ \
-      pandas/io/clipboard/ \
-      pandas/io/json/ \
-      pandas/io/excel/ \
-      pandas/io/parsers/ \
-      pandas/io/sas/ \
-      pandas/io/sql.py \
-      pandas/io/formats/format.py \
-      pandas/io/formats/style.py \
-      pandas/io/stata.py \
-      pandas/tseries/
+      pandas/io/ \
+      pandas/tseries/ \
+      pandas/util/ \
+      pandas/_typing.py \
+      pandas/_version.py \
+      pandas/conftest.py \
+      pandas/testing.py
     RET=$(($RET + $?)) ; echo $MSG "DONE"
 
     MSG='Cython Doctests' ; echo $MSG

pandas/_config/config.py

@@ -411,7 +411,7 @@ class option_context(ContextDecorator):
     Examples
     --------
     >>> with option_context('display.max_rows', 10, 'display.max_columns', 5):
-    ...     ...
+    ...     pass
     """
 
     def __init__(self, *args):

pandas/_testing/__init__.py

@@ -431,7 +431,7 @@ def _make_timeseries(start="2000-01-01", end="2000-12-31", freq="1D", seed=None)
 
     Examples
     --------
-    >>> _make_timeseries()
+    >>> _make_timeseries()  # doctest: +SKIP
                   id    name         x         y
     timestamp
     2000-01-01   982   Frank  0.031261  0.986727

pandas/_testing/_io.py

@@ -167,7 +167,7 @@ def network(
       ... def test_network():
       ...     with pd.io.common.urlopen("rabbit://bonanza.com"):
       ...         pass
-      >>> test_network()
+      >>> test_network()  # doctest: +SKIP
       Traceback
          ...
       URLError: <urlopen error unknown url type: rabbit>
@@ -189,7 +189,7 @@ def network(
         ... def test_something():
         ...     print("I ran!")
         ...     raise ValueError("Failure")
-        >>> test_something()
+        >>> test_something()  # doctest: +SKIP
         Traceback (most recent call last):
             ...
 

pandas/_testing/asserters.py

@@ -193,16 +193,15 @@ def _get_tol_from_less_precise(check_less_precise: bool | int) -> float:
     --------
     >>> # Using check_less_precise as a bool:
     >>> _get_tol_from_less_precise(False)
-    0.5e-5
+    5e-06
     >>> _get_tol_from_less_precise(True)
-    0.5e-3
+    0.0005
     >>> # Using check_less_precise as an int representing the decimal
     >>> # tolerance intended:
     >>> _get_tol_from_less_precise(2)
-    0.5e-2
+    0.005
     >>> _get_tol_from_less_precise(8)
-    0.5e-8
-
+    5e-09
     """
     if isinstance(check_less_precise, bool):
         if check_less_precise:

pandas/_testing/contexts.py

@@ -54,13 +54,13 @@ def set_timezone(tz: str):
     --------
     >>> from datetime import datetime
     >>> from dateutil.tz import tzlocal
-    >>> tzlocal().tzname(datetime.now())
+    >>> tzlocal().tzname(datetime(2021, 1, 1))  # doctest: +SKIP
     'IST'
 
     >>> with set_timezone('US/Eastern'):
-    ...     tzlocal().tzname(datetime.now())
+    ...     tzlocal().tzname(datetime(2021, 1, 1))
     ...
-    'EDT'
+    'EST'
     """
     import os
     import time

pandas/io/formats/style_render.py

@@ -1062,7 +1062,7 @@ def format_index(
         --------
         Using ``na_rep`` and ``precision`` with the default ``formatter``
 
-        >>> df = pd.DataFrame([[1, 2, 3]], columns=[2.0, np.nan, 4.0]])
+        >>> df = pd.DataFrame([[1, 2, 3]], columns=[2.0, np.nan, 4.0])
         >>> df.style.format_index(axis=1, na_rep='MISS', precision=3)  # doctest: +SKIP
             2.000    MISS   4.000
         0       1       2       3
@@ -1096,6 +1096,7 @@ def format_index(
 
         >>> df = pd.DataFrame([[1, 2, 3]], columns=['"A"', 'A&B', None])
         >>> s = df.style.format_index('$ {0}', axis=1, escape="html", na_rep="NA")
+        ...  # doctest: +SKIP
         <th .. >$ &#34;A&#34;</th>
         <th .. >$ A&amp;B</th>
         <th .. >NA</td>
@@ -1811,7 +1812,7 @@ def _parse_latex_header_span(
 
     Examples
     --------
-    >>> cell = {'display_value':'text', 'attributes': 'colspan="3"'}
+    >>> cell = {'cellstyle': '', 'display_value':'text', 'attributes': 'colspan="3"'}
     >>> _parse_latex_header_span(cell, 't', 'c')
     '\\multicolumn{3}{c}{text}'
     """

pandas/util/_decorators.py

@@ -122,19 +122,19 @@ def deprecate_kwarg(
     >>> f(columns='should work ok')
     should work ok
 
-    >>> f(cols='should raise warning')
+    >>> f(cols='should raise warning')  # doctest: +SKIP
     FutureWarning: cols is deprecated, use columns instead
       warnings.warn(msg, FutureWarning)
     should raise warning
 
-    >>> f(cols='should error', columns="can\'t pass do both")
+    >>> f(cols='should error', columns="can\'t pass do both")  # doctest: +SKIP
     TypeError: Can only specify 'cols' or 'columns', not both
 
     >>> @deprecate_kwarg('old', 'new', {'yes': True, 'no': False})
     ... def f(new=False):
     ...     print('yes!' if new else 'no!')
     ...
-    >>> f(old='yes')
+    >>> f(old='yes')  # doctest: +SKIP
     FutureWarning: old='yes' is deprecated, use new=True instead
       warnings.warn(msg, FutureWarning)
     yes!
@@ -145,14 +145,14 @@ def deprecate_kwarg(
     ... def f(cols='', another_param=''):
     ...     print(cols)
     ...
-    >>> f(cols='should raise warning')
+    >>> f(cols='should raise warning')  # doctest: +SKIP
     FutureWarning: the 'cols' keyword is deprecated and will be removed in a
     future version please takes steps to stop use of 'cols'
     should raise warning
-    >>> f(another_param='should not raise warning')
+    >>> f(another_param='should not raise warning')  # doctest: +SKIP
     should not raise warning
 
-    >>> f(cols='should raise warning', another_param='')
+    >>> f(cols='should raise warning', another_param='')  # doctest: +SKIP
     FutureWarning: the 'cols' keyword is deprecated and will be removed in a
     future version please takes steps to stop use of 'cols'
     should raise warning

pandas/util/_validators.py

@@ -281,14 +281,15 @@ def validate_axis_style_args(data, args, kwargs, arg_name, method_name):
 
     Examples
     --------
-    >>> df._validate_axis_style_args((str.upper,), {'columns': id},
-    ...                              'mapper', 'rename')
-    {'columns': <function id>, 'index': <method 'upper' of 'str' objects>}
+    >>> df = pd.DataFrame(range(2))
+    >>> validate_axis_style_args(df, (str.upper,), {'columns': id},
+    ...                          'mapper', 'rename')
+    {'columns': <built-in function id>, 'index': <method 'upper' of 'str' objects>}
 
     This emits a warning
-    >>> df._validate_axis_style_args((str.upper, id), {},
-    ...                              'mapper', 'rename')
-    {'columns': <function id>, 'index': <method 'upper' of 'str' objects>}
+    >>> validate_axis_style_args(df, (str.upper, id), {},
+    ...                          'mapper', 'rename')
+    {'index': <method 'upper' of 'str' objects>, 'columns': <built-in function id>}
     """
     # TODO: Change to keyword-only args and remove all this