BUG: Docs won't build (Unexpected warning in `user_guide/timeseries.rst`)

[Huanghz2001]

Pandas version checks

• I have checked that this issue has not already been reported.

• I have confirmed this bug exists on the latest version of pandas.

• I have confirmed this bug exists on the main branch of pandas.

Reproducible Example

git clone https://github.com/pandas-dev/pandas.git
cd pandas
python -m pip install -r requirements-dev.txt
python -m pip install -ve . --no-build-isolation --config-settings editable-verbose=true
cd doc

python make.py html
python make.py clean
python make.py --single user_guide/timeseries.rst

Issue Description

Running python make.py html to build the whole documentation, it fails when building user_guide/timeseries.rst:

Sphinx parallel build error:
RuntimeError: Unexpected warning in `/home1/hhz/pandas_main/pandas/doc/source/user_guide/timeseries.rst` line 218

Then run python make.py --single user_guide/timeseries.rst to see details:

WARNING: ources... [100%] user_guide/timeseries
>>>-------------------------------------------------------------------------
Warning in /home1/hhz/pandas_main/pandas/doc/source/user_guide/timeseries.rst at block ending on line 218
Specify :okwarning: as an option in the ipython:: block to suppress this message
----------------------------------------------------------------------------
<ipython-input-44-ffc04f3bd908>:1: UserWarning: Could not infer format, so each element will be parsed individually, falling back to `dateutil`. To ensure parsing is consistent and as-expected, please specify a format.
  pd.to_datetime(pd.Series(["Jul 31, 2009", "Jan 10, 2010", None]))
<<<-------------------------------------------------------------------------

Exception occurred:
  File "/home1/hhz/miniconda3/envs/pandas_main/lib/python3.11/site-packages/IPython/sphinxext/ipython_directive.py", line 602, in process_input
    raise RuntimeError(
RuntimeError: Unexpected warning in `/home1/hhz/pandas_main/pandas/doc/source/user_guide/timeseries.rst` line 218
The full traceback has been saved in /tmp/sphinx-err-mnsayjoe.log, if you want to report the issue to the developers.
Please also report this if it was a user error, so that a better error message can be provided next time.
A bug report can be filed in the tracker at <https://github.com/sphinx-doc/sphinx/issues>. Thanks!

The UserWarning for pd.to_datetime(pd.Series(["Jul 31, 2009", "Jan 10, 2010", None])) seems to be strange because no warning occurs when I directly run this code in ipython. Full traceback in /tmp/sphinx-err-mnsayjoe.log:

# Platform:         linux; (Linux-6.2.0-39-generic-x86_64-with-glibc2.35)
# Sphinx version:   7.2.6
# Python version:   3.11.0 (CPython)
# Docutils version: 0.20.1
# Jinja2 version:   3.1.2
# Pygments version: 2.17.2

# Last messages:
#   [new config]
#   2 added, 0 changed, 0 removed

#   reading sources... [ 50%]
#   index
#   

#   reading sources... [100%]
#   user_guide/timeseries
#   

# Loaded extensions:
#   sphinx.ext.mathjax (7.2.6)
#   alabaster (0.7.13)
#   sphinxcontrib.applehelp (1.0.7)
#   sphinxcontrib.devhelp (1.0.5)
#   sphinxcontrib.htmlhelp (2.0.4)
#   sphinxcontrib.serializinghtml (1.1.9)
#   sphinxcontrib.qthelp (1.0.6)
#   contributors (0.1)
#   IPython.sphinxext.ipython_directive (unknown version)
#   IPython.sphinxext.ipython_console_highlighting (unknown version)
#   matplotlib.sphinxext.plot_directive (3.8.2)
#   sphinx.ext.autodoc.preserve_defaults (7.2.6)
#   sphinx.ext.autodoc.type_comment (7.2.6)
#   sphinx.ext.autodoc.typehints (7.2.6)
#   sphinx.ext.autodoc (7.2.6)
#   sphinx.ext.autosummary (7.2.6)
#   numpydoc (1.6.0)
#   sphinx_copybutton (0.5.2)
#   sphinx_design (0.5.0)
#   sphinx.ext.coverage (7.2.6)
#   sphinx.ext.doctest (7.2.6)
#   sphinx.ext.extlinks (7.2.6)
#   sphinx.ext.ifconfig (7.2.6)
#   sphinx.ext.intersphinx (7.2.6)
#   sphinx.ext.linkcode (7.2.6)
#   sphinx.ext.todo (7.2.6)
#   nbsphinx (0.9.3)
#   pydata_sphinx_theme (unknown version)

# Traceback:
Traceback (most recent call last):
  File "/home1/hhz/miniconda3/envs/pandas_main/lib/python3.11/site-packages/sphinx/cmd/build.py", line 298, in build_main
    app.build(args.force_all, args.filenames)
  File "/home1/hhz/miniconda3/envs/pandas_main/lib/python3.11/site-packages/sphinx/application.py", line 355, in build
    self.builder.build_update()
  File "/home1/hhz/miniconda3/envs/pandas_main/lib/python3.11/site-packages/sphinx/builders/__init__.py", line 293, in build_update
    self.build(to_build,
  File "/home1/hhz/miniconda3/envs/pandas_main/lib/python3.11/site-packages/sphinx/builders/__init__.py", line 313, in build
    updated_docnames = set(self.read())
                           ^^^^^^^^^^^
  File "/home1/hhz/miniconda3/envs/pandas_main/lib/python3.11/site-packages/sphinx/builders/__init__.py", line 420, in read
    self._read_serial(docnames)
  File "/home1/hhz/miniconda3/envs/pandas_main/lib/python3.11/site-packages/sphinx/builders/__init__.py", line 441, in _read_serial
    self.read_doc(docname)
  File "/home1/hhz/miniconda3/envs/pandas_main/lib/python3.11/site-packages/sphinx/builders/__init__.py", line 498, in read_doc
    publisher.publish()
  File "/home1/hhz/miniconda3/envs/pandas_main/lib/python3.11/site-packages/docutils/core.py", line 234, in publish
    self.document = self.reader.read(self.source, self.parser,
                    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home1/hhz/miniconda3/envs/pandas_main/lib/python3.11/site-packages/sphinx/io.py", line 105, in read
    self.parse()
  File "/home1/hhz/miniconda3/envs/pandas_main/lib/python3.11/site-packages/docutils/readers/__init__.py", line 76, in parse
    self.parser.parse(self.input, document)
  File "/home1/hhz/miniconda3/envs/pandas_main/lib/python3.11/site-packages/sphinx/parsers.py", line 81, in parse
    self.statemachine.run(inputlines, document, inliner=self.inliner)
  File "/home1/hhz/miniconda3/envs/pandas_main/lib/python3.11/site-packages/docutils/parsers/rst/states.py", line 169, in run
    results = StateMachineWS.run(self, input_lines, input_offset,
              ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home1/hhz/miniconda3/envs/pandas_main/lib/python3.11/site-packages/docutils/statemachine.py", line 233, in run
    context, next_state, result = self.check_line(
                                  ^^^^^^^^^^^^^^^^
  File "/home1/hhz/miniconda3/envs/pandas_main/lib/python3.11/site-packages/docutils/statemachine.py", line 445, in check_line
    return method(match, context, next_state)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home1/hhz/miniconda3/envs/pandas_main/lib/python3.11/site-packages/docutils/parsers/rst/states.py", line 3024, in text
    self.section(title.lstrip(), source, style, lineno + 1, messages)
  File "/home1/hhz/miniconda3/envs/pandas_main/lib/python3.11/site-packages/docutils/parsers/rst/states.py", line 325, in section
    self.new_subsection(title, lineno, messages)
  File "/home1/hhz/miniconda3/envs/pandas_main/lib/python3.11/site-packages/docutils/parsers/rst/states.py", line 391, in new_subsection
    newabsoffset = self.nested_parse(
                   ^^^^^^^^^^^^^^^^^^
  File "/home1/hhz/miniconda3/envs/pandas_main/lib/python3.11/site-packages/docutils/parsers/rst/states.py", line 279, in nested_parse
    state_machine.run(block, input_offset, memo=self.memo,
  File "/home1/hhz/miniconda3/envs/pandas_main/lib/python3.11/site-packages/docutils/parsers/rst/states.py", line 195, in run
    results = StateMachineWS.run(self, input_lines, input_offset)
              ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home1/hhz/miniconda3/envs/pandas_main/lib/python3.11/site-packages/docutils/statemachine.py", line 233, in run
    context, next_state, result = self.check_line(
                                  ^^^^^^^^^^^^^^^^
  File "/home1/hhz/miniconda3/envs/pandas_main/lib/python3.11/site-packages/docutils/statemachine.py", line 445, in check_line
    return method(match, context, next_state)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home1/hhz/miniconda3/envs/pandas_main/lib/python3.11/site-packages/docutils/parsers/rst/states.py", line 2785, in underline
    self.section(title, source, style, lineno - 1, messages)
  File "/home1/hhz/miniconda3/envs/pandas_main/lib/python3.11/site-packages/docutils/parsers/rst/states.py", line 325, in section
    self.new_subsection(title, lineno, messages)
  File "/home1/hhz/miniconda3/envs/pandas_main/lib/python3.11/site-packages/docutils/parsers/rst/states.py", line 391, in new_subsection
    newabsoffset = self.nested_parse(
                   ^^^^^^^^^^^^^^^^^^
  File "/home1/hhz/miniconda3/envs/pandas_main/lib/python3.11/site-packages/docutils/parsers/rst/states.py", line 279, in nested_parse
    state_machine.run(block, input_offset, memo=self.memo,
  File "/home1/hhz/miniconda3/envs/pandas_main/lib/python3.11/site-packages/docutils/parsers/rst/states.py", line 195, in run
    results = StateMachineWS.run(self, input_lines, input_offset)
              ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home1/hhz/miniconda3/envs/pandas_main/lib/python3.11/site-packages/docutils/statemachine.py", line 233, in run
    context, next_state, result = self.check_line(
                                  ^^^^^^^^^^^^^^^^
  File "/home1/hhz/miniconda3/envs/pandas_main/lib/python3.11/site-packages/docutils/statemachine.py", line 445, in check_line
    return method(match, context, next_state)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home1/hhz/miniconda3/envs/pandas_main/lib/python3.11/site-packages/docutils/parsers/rst/states.py", line 2355, in explicit_markup
    nodelist, blank_finish = self.explicit_construct(match)
                             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home1/hhz/miniconda3/envs/pandas_main/lib/python3.11/site-packages/docutils/parsers/rst/states.py", line 2367, in explicit_construct
    return method(self, expmatch)
           ^^^^^^^^^^^^^^^^^^^^^^
  File "/home1/hhz/miniconda3/envs/pandas_main/lib/python3.11/site-packages/docutils/parsers/rst/states.py", line 2104, in directive
    return self.run_directive(
           ^^^^^^^^^^^^^^^^^^^
  File "/home1/hhz/miniconda3/envs/pandas_main/lib/python3.11/site-packages/docutils/parsers/rst/states.py", line 2154, in run_directive
    result = directive_instance.run()
             ^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home1/hhz/miniconda3/envs/pandas_main/lib/python3.11/site-packages/IPython/sphinxext/ipython_directive.py", line 1033, in run
    rows, figure = self.shell.process_block(block)
                   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home1/hhz/miniconda3/envs/pandas_main/lib/python3.11/site-packages/IPython/sphinxext/ipython_directive.py", line 732, in process_block
    self.process_input(data, input_prompt, lineno)
  File "/home1/hhz/miniconda3/envs/pandas_main/lib/python3.11/site-packages/IPython/sphinxext/ipython_directive.py", line 602, in process_input
    raise RuntimeError(
RuntimeError: Unexpected warning in `/home1/hhz/pandas_main/pandas/doc/source/user_guide/timeseries.rst` line 218

Expected Behavior

HTML doc successfully built.

Installed Versions

INSTALLED VERSIONS

commit : b2bca5e
python : 3.11.0.final.0
python-bits : 64
OS : Linux
OS-release : 6.2.0-39-generic
Version : #40~22.04.1-Ubuntu SMP PREEMPT_DYNAMIC Thu Nov 16 10:53:04 UTC 2
machine : x86_64
processor : x86_64
byteorder : little
LC_ALL : None
LANG : en_US.UTF-8
LOCALE : en_US.UTF-8

pandas : 2.3.0.dev0+46.gb2bca5e965
numpy : 1.26.3
pytz : 2023.3.post1
dateutil : 2.8.2
setuptools : 68.2.2
pip : 23.3.1
Cython : 3.0.5
pytest : 7.4.4
hypothesis : 6.92.2
sphinx : 7.2.6
blosc : 1.11.1
feather : None
xlsxwriter : 3.1.9
lxml.etree : 5.0.0
html5lib : 1.1
pymysql : 1.4.6
psycopg2 : 2.9.9
jinja2 : 3.1.2
IPython : 8.19.0
pandas_datareader : None
adbc-driver-postgresql: None
adbc-driver-sqlite : None
bs4 : 4.12.2
bottleneck : 1.3.7
dataframe-api-compat : None
fastparquet : 2023.10.1
fsspec : 2023.12.2
gcsfs : 2023.12.2post1
matplotlib : 3.8.2
numba : 0.58.1
numexpr : 2.8.8
odfpy : None
openpyxl : 3.1.2
pandas_gbq : None
pyarrow : 14.0.2
pyreadstat : 1.2.6
python-calamine : None
pyxlsb : 1.0.10
s3fs : 2023.12.2
scipy : 1.11.4
sqlalchemy : 2.0.25
tables : 3.9.2
tabulate : 0.9.0
xarray : 2023.12.0
xlrd : 2.0.1
zstandard : 0.22.0
tzdata : 2023.4
qtpy : None
pyqt5 : None

[rhshadrach]

The UserWarning for pd.to_datetime(pd.Series(["Jul 31, 2009", "Jan 10, 2010", None])) seems to be strange because no warning occurs when I directly run this code in ipython.

This suggests to me you are using two different pythons when you build docs vs when you run in ipython. When you build and install pandas, what python is used?

[Huanghz2001]

@rhshadrach
I directly run the commands python make.py and ipython in the same conda environment. I have checked that they use the same python.

$ which ipython
/home1/hhz/miniconda3/envs/pandas_main/bin/ipython
$ which python
/home1/hhz/miniconda3/envs/pandas_main/bin/python
$ cat /home1/hhz/miniconda3/envs/pandas_main/bin/ipython
#!/home1/hhz/miniconda3/envs/pandas_main/bin/python
# -*- coding: utf-8 -*-
import re
import sys
from IPython import start_ipython
if __name__ == '__main__':
    sys.argv[0] = re.sub(r'(-script\.pyw|\.exe)?$', '', sys.argv[0])
    sys.exit(start_ipython())

[rhshadrach]

Very odd. I would suggest to try recreating your environment, but from the commands above I believe you've already done that.

[melissawm]

Hi all, I am getting the same issue. Adding :okwarning: to this block

pandas/doc/source/user_guide/timeseries.rst

Lines 199 to 204 in ec3eddd

	.. ipython:: python
	pd.to_datetime(pd.Series(["Jul 31, 2009", "Jan 10, 2010", None]))
	pd.to_datetime(["2005/11/23", "2010/12/31"])

solves the issue for me. I'm happy to submit a PR if that's the acceptable solution. Cheers!

[rhshadrach]

@melissawm - If you run this code on its own (outside building the docs), what's the warning you're seeing?

[melissawm]

Here you go, no warnings:

(pandas-dev) ➜  ~ ipython 
Python 3.10.14 | packaged by conda-forge | (main, Mar 20 2024, 12:45:18) [GCC 12.3.0]
Type 'copyright', 'credits' or 'license' for more information
IPython 8.22.2 -- An enhanced Interactive Python. Type '?' for help.

In [1]: import pandas as pd
+ /home/melissa/micromamba/envs/pandas-dev/bin/ninja
[1/1] Generating write_version_file with a custom command

In [2]: pd.to_datetime(pd.Series(["Jul 31, 2009", "Jan 10, 2010", None])
   ...: )
Out[2]: 
0   2009-07-31
1   2010-01-10
2          NaT
dtype: datetime64[ns]

In [3]: pd.to_datetime(["2005/11/23", "2010/12/31"])
Out[3]: DatetimeIndex(['2005-11-23', '2010-12-31'], dtype='datetime64[ns]', freq=None)

In [4]: pd.__version__
Out[4]: '2.2.0.dev0+1627.g9cd5e5546c.dirty'

In [5]: 

[rhshadrach]

Thanks @melissawm. But this is odd - I don't know what :okwarning: would do to resolve the issue if you're not seeing a warning. I'd be hesitant to add such a line when we don't see the failing on the CI without understanding further.

[panda-34]

This error happens because sphinx selects user locale, so then '%B' format in strftime returns localized month names and pandas' date format inferring with english month names fails. To prevent this error you can restore locale to default in conf.py:

import locale
locale.setlocale(locale.LC_ALL, locale='C')

[rhshadrach]

Thanks @panda-34 - that explains the trouble we've had reproducing. Will confirm on my end in the next few days, if anyone else would like to do it'd be appreciated as well!

[melissawm]

I'm afraid I get a different error now 😅

I can open another issue to not pollute this one but I can also do some digging myself. I installed using the instructions on the contributing docs:

(pandas-dev) ➜  doc git:(main) ✗ python make.py html
+ /home/melissa/micromamba/envs/pandas-dev/bin/ninja
[1/1] Generating write_version_file with a custom command
Executando Sphinx v8.1.3
+ /home/melissa/micromamba/envs/pandas-dev/bin/ninja
[1/1] Generating write_version_file with a custom command
carregando traduções [en]… feito
criando o diretório de saída... feito
Convertendo `source_suffix = ['.rst']` para `source_suffix = {'.rst': 'restructuredtext'}`.
[autosummary] gerando autosummary para: development/community.rst, development/contributing.rst, development/contributing_codebase.rst, development/contributing_docstring.rst, development/contributing_documentation.rst, development/contributing_environment.rst, development/contributing_gitpod.rst, development/copy_on_write.rst, development/debugging_extensions.rst, development/developer.rst, ..., whatsnew/v2.1.1.rst, whatsnew/v2.1.2.rst, whatsnew/v2.1.3.rst, whatsnew/v2.1.4.rst, whatsnew/v2.2.0.rst, whatsnew/v2.2.1.rst, whatsnew/v2.2.2.rst, whatsnew/v2.2.3.rst, whatsnew/v2.3.0.rst, whatsnew/v3.0.0.rst
[autosummary] gerando autosummary para: /home/melissa/projects/pandas/doc/source/reference/api/pandas.ArrowDtype.rst, /home/melissa/projects/pandas/doc/source/reference/api/pandas.BooleanDtype.rst, /home/melissa/projects/pandas/doc/source/reference/api/pandas.Categorical.__array__.rst, /home/melissa/projects/pandas/doc/source/reference/api/pandas.Categorical.add_categories.rst, /home/melissa/projects/pandas/doc/source/reference/api/pandas.Categorical.as_ordered.rst, /home/melissa/projects/pandas/doc/source/reference/api/pandas.Categorical.as_unordered.rst, /home/melissa/projects/pandas/doc/source/reference/api/pandas.Categorical.categories.rst, /home/melissa/projects/pandas/doc/source/reference/api/pandas.Categorical.codes.rst, /home/melissa/projects/pandas/doc/source/reference/api/pandas.Categorical.dtype.rst, /home/melissa/projects/pandas/doc/source/reference/api/pandas.Categorical.from_codes.rst, ..., /home/melissa/projects/pandas/doc/source/reference/api/pandas.tseries.offsets.YearEnd.n.rst, /home/melissa/projects/pandas/doc/source/reference/api/pandas.tseries.offsets.YearEnd.name.rst, /home/melissa/projects/pandas/doc/source/reference/api/pandas.tseries.offsets.YearEnd.nanos.rst, /home/melissa/projects/pandas/doc/source/reference/api/pandas.tseries.offsets.YearEnd.normalize.rst, /home/melissa/projects/pandas/doc/source/reference/api/pandas.tseries.offsets.YearEnd.rst, /home/melissa/projects/pandas/doc/source/reference/api/pandas.tseries.offsets.YearEnd.rule_code.rst, /home/melissa/projects/pandas/doc/source/reference/api/pandas.unique.rst, /home/melissa/projects/pandas/doc/source/reference/api/pandas.util.hash_array.rst, /home/melissa/projects/pandas/doc/source/reference/api/pandas.util.hash_pandas_object.rst, /home/melissa/projects/pandas/doc/source/reference/api/pandas.wide_to_long.rst
carregando inventário intersphinx  'dateutil' de https://dateutil.readthedocs.io/en/latest/objects.inv ...
carregando inventário intersphinx  'matplotlib' de https://matplotlib.org/stable/objects.inv ...
carregando inventário intersphinx  'numpy' de https://numpy.org/doc/stable/objects.inv ...
carregando inventário intersphinx  'python' de https://docs.python.org/3/objects.inv ...
carregando inventário intersphinx  'scipy' de https://docs.scipy.org/doc/scipy/objects.inv ...
carregando inventário intersphinx  'pyarrow' de https://arrow.apache.org/docs/objects.inv ...
Escrevendo resultado do modelo avaliado para /home/melissa/projects/pandas/doc/build/html/_static/nbsphinx-code-cells.css
construindo [mo]: alvos para 0 arquivos po que estão desatualizados
escrevendo saída… 
construindo [html]: alvos para 184 arquivos fonte que estão desatualizados
atualizando ambiente: [nova configuração] 2266 adicionado(s), 0 alterado(s), 0 removido(s)
lendo fontes… [ 17%] reference/api/pandas.ExcelWriter .. reference/api/pandas.Index.get_loc
Sphinx parallel build error:
RuntimeError: Unexpected exception in `/home/melissa/projects/pandas/doc/source/whatsnew/v0.23.0.rst` line None
(pandas-dev) ➜  doc git:(main) ✗