DOC: Error in building documentation

[DominikBerger01]

Pandas version checks

• I have checked that the issue still exists on the latest versions of the docs on main here

Location of the documentation

Documentation build.

Documentation problem

I followed the contribution guide : https://pandas.pydata.org/docs/dev/development/contributing_environment.html
to setup my environment with the provided Dockerfile. (Note I'm working on main branch)
Then I tried building the docs following this guide https://pandas.pydata.org/docs/dev/development/contributing_documentation.html

But I received the following error. Just want to know if lately a bug has been introduced or if it is on my side.

loading intersphinx inventory from https://dateutil.readthedocs.io/en/latest/objects.inv...
loading intersphinx inventory from https://matplotlib.org/stable/objects.inv...
loading intersphinx inventory from https://numpy.org/doc/stable/objects.inv...
loading intersphinx inventory from https://pandas-gbq.readthedocs.io/en/latest/objects.inv...
loading intersphinx inventory from https://pylib.readthedocs.io/en/latest/objects.inv...
loading intersphinx inventory from https://docs.python.org/3/objects.inv...
loading intersphinx inventory from https://docs.scipy.org/doc/scipy/objects.inv...
loading intersphinx inventory from https://arrow.apache.org/docs/objects.inv...
building [mo]: targets for 0 po files that are out of date
writing output... 
building [html]: targets for 171 source files that are out of date
updating environment: [new config] 2468 added, 0 changed, 0 removed
reading sources... [ 71%] reference/api/pandas.tseries.offsets.BusinessMonthEnd.is_anchored .. reference/api/pandas.tseries.offsets.CustomBusinessMonthBegin.is_anchorreading sources... [ 75%] reference/api/pandas.tseries.offsets.CustomBusinessMonthBegin.is_month_end .. reference/api/pandas.tseries.offsets.Day.is_year_end         
Sphinx parallel build error:
RuntimeError: Non Expected warning in `/home/pandas/doc/source/user_guide/basics.rst` line 2150

Pandas Version

>>> import pandas
>>> pandas.__version__
'2.1.0.dev0+823.g7a7d684b38'

I checked the line referenced in the error message but didn't find anything suspicious. But I must note I'm new to Sphinx.

Suggested fix for documentation

Not sure about issue yet.

[lithomas1]

Can you share the warning message if there is one?

[DominikBerger01]

Can you share the warning message if there is one?

That is all I can get out:

root@1cffd0126e92:/home/pandas/doc# python make.py html -v -W
Running Sphinx v6.2.1
Pandoc not installed. Skipping notebooks.
Adding copy buttons to code blocks...
Adding toggle buttons to code blocks...
locale_dir /home/pandas/doc/source/locales/en/LC_MESSAGES does not exists
[autosummary] generating autosummary for: 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/v1.4.3.rst, whatsnew/v1.4.4.rst, whatsnew/v1.5.0.rst, whatsnew/v1.5.1.rst, whatsnew/v1.5.2.rst, whatsnew/v1.5.3.rst, whatsnew/v2.0.0.rst, whatsnew/v2.0.1.rst, whatsnew/v2.0.2.rst, whatsnew/v2.1.0.rst
loading intersphinx inventory from https://dateutil.readthedocs.io/en/latest/objects.inv...
loading intersphinx inventory from https://matplotlib.org/stable/objects.inv...
loading intersphinx inventory from https://numpy.org/doc/stable/objects.inv...
loading intersphinx inventory from https://pandas-gbq.readthedocs.io/en/latest/objects.inv...
loading intersphinx inventory from https://pylib.readthedocs.io/en/latest/objects.inv...
loading intersphinx inventory from https://docs.python.org/3/objects.inv...
loading intersphinx inventory from https://docs.scipy.org/doc/scipy/objects.inv...
loading intersphinx inventory from https://arrow.apache.org/docs/objects.inv...
locale_dir /home/pandas/doc/source/locales/en/LC_MESSAGES does not exists
building [mo]: targets for 0 po files that are out of date
writing output... 
building [html]: targets for 2468 source files that are out of date
updating environment: locale_dir /home/pandas/doc/source/locales/en/LC_MESSAGES does not exists
[new config] 2468 added, 0 changed, 0 removed
reading sources... [  3%] development/community .. reference/api/pandas.DataFrame.any
reading sources... [  6%] reference/api/pandas.DataFrame.apply .. reference/api/pandas.DataFrame.iterrows
reading sources... [  9%] reference/api/pandas.DataFrame.itertuples .. reference/api/pandas.DataFrame.set_index
reading sources... [ 12%] reference/api/pandas.DataFrame.shape .. reference/api/pandas.DatetimeIndex.is_month_start
reading sources... [ 15%] reference/api/pandas.DatetimeIndex.is_quarter_end .. reference/api/pandas.Index.droplevel
reading sources... [ 18%] reference/api/pandas.Index.dropna .. reference/api/pandas.Index.union
reading sources... [ 21%] reference/api/pandas.Index.unique .. reference/api/pandas.NamedAgg.count
reading sources... [ 25%] reference/api/pandas.NamedAgg.index .. reference/api/pandas.Series.argmin
reading sources... [ 28%] reference/api/pandas.Series.argsort .. reference/api/pandas.Series.dt.minute
reading sources... [ 31%] reference/api/pandas.Series.dt.month .. reference/api/pandas.Series.memory_usage
reading sources... [ 34%] reference/api/pandas.Series.min .. reference/api/pandas.Series.str.cat
reading sources... [ 37%] reference/api/pandas.Series.str.center .. reference/api/pandas.Series.tolist
reading sources... [ 40%] reference/api/pandas.Series.transform .. reference/api/pandas.Timestamp.fromtimestamp
reading sources... [ 43%] reference/api/pandas.Timestamp.hour .. reference/api/pandas.api.extensions.ExtensionArray.isin
reading sources... [ 46%] reference/api/pandas.api.extensions.ExtensionArray.isna .. reference/api/pandas.arrays.BooleanArray
reading sources... [ 50%] reference/api/pandas.arrays.DatetimeArray .. reference/api/pandas.core.groupby.DataFrameGroupBy.std
reading sources... [ 53%] reference/api/pandas.core.groupby.DataFrameGroupBy.sum .. reference/api/pandas.core.resample.Resampler.get_group
reading sources... [ 56%] reference/api/pandas.core.resample.Resampler.groups .. reference/api/pandas.errors.DtypeWarning
reading sources... [ 59%] reference/api/pandas.errors.DuplicateLabelError .. reference/api/pandas.io.formats.style.Styler.text_gradient
reading sources... [ 62%] reference/api/pandas.io.formats.style.Styler.to_excel .. reference/api/pandas.tseries.offsets.BQuarterBegin.copy
reading sources... [ 65%] reference/api/pandas.tseries.offsets.BQuarterBegin.freqstr .. reference/api/pandas.tseries.offsets.BYearEnd.normalize
reading sources... [ 68%] reference/api/pandas.tseries.offsets.BYearEnd.rollback .. reference/api/pandas.tseries.offsets.BusinessMonthEnd.freqstr
reading sources... [ 71%] reference/api/pandas.tseries.offsets.BusinessMonthEnd.is_anchored .. reference/api/pandas.tseries.offsets.CustomBusinessMonthBegin.is_anchored
reading sources... [ 75%] reference/api/pandas.tseries.offsets.CustomBusinessMonthBegin.is_month_end .. reference/api/pandas.tseries.offsets.Day.is_year_end

Traceback (most recent call last):
  File "/usr/local/lib/python3.10/site-packages/sphinx/cmd/build.py", line 285, in build_main
    app.build(args.force_all, args.filenames)
  File "/usr/local/lib/python3.10/site-packages/sphinx/application.py", line 353, in build
    self.builder.build_update()
  File "/usr/local/lib/python3.10/site-packages/sphinx/builders/__init__.py", line 311, in build_update
    self.build(to_build,
  File "/usr/local/lib/python3.10/site-packages/sphinx/builders/__init__.py", line 328, in build
    updated_docnames = set(self.read())
  File "/usr/local/lib/python3.10/site-packages/sphinx/builders/__init__.py", line 433, in read
    self._read_parallel(docnames, nproc=self.app.parallel)
  File "/usr/local/lib/python3.10/site-packages/sphinx/builders/__init__.py", line 489, in _read_parallel
    tasks.join()
  File "/usr/local/lib/python3.10/site-packages/sphinx/util/parallel.py", line 99, in join
    if not self._join_one():
  File "/usr/local/lib/python3.10/site-packages/sphinx/util/parallel.py", line 119, in _join_one
    raise SphinxParallelError(*result)
sphinx.errors.SphinxParallelError: RuntimeError: Non Expected warning in `/home/pandas/doc/source/user_guide/basics.rst` line 2150

Sphinx parallel build error:
RuntimeError: Non Expected warning in `/home/pandas/doc/source/user_guide/basics.rst` line 2150
root@1cffd0126e92:/home/pandas/doc# 

Can't get the specific warning causing the error.

[lithomas1]

That sucks, maybe building in serial yields more information?

[DominikBerger01]

That sucks, maybe building in serial yields more information?

It did....

WARNING: 
>>>-------------------------------------------------------------------------
Warning in /home/pandas/doc/source/user_guide/basics.rst at block ending on line 2150
Specify :okwarning: as an option in the ipython:: block to suppress this message
----------------------------------------------------------------------------
<ipython-input-346-c8098573a8e8>:5: RuntimeWarning: invalid value encountered in cast
  "C": pd.Series(np.array(np.random.randn(8), dtype="uint8")),
<<<-------------------------------------------------------------------------

Traceback (most recent call last):
  File "/usr/local/lib/python3.10/site-packages/sphinx/cmd/build.py", line 285, in build_main
    app.build(args.force_all, args.filenames)
  File "/usr/local/lib/python3.10/site-packages/sphinx/application.py", line 353, in build
    self.builder.build_update()
  File "/usr/local/lib/python3.10/site-packages/sphinx/builders/__init__.py", line 311, in build_update
    self.build(to_build,
  File "/usr/local/lib/python3.10/site-packages/sphinx/builders/__init__.py", line 328, in build
    updated_docnames = set(self.read())
  File "/usr/local/lib/python3.10/site-packages/sphinx/builders/__init__.py", line 435, in read
    self._read_serial(docnames)
  File "/usr/local/lib/python3.10/site-packages/sphinx/builders/__init__.py", line 456, in _read_serial
    self.read_doc(docname)
  File "/usr/local/lib/python3.10/site-packages/sphinx/builders/__init__.py", line 512, in read_doc
    publisher.publish()
  File "/usr/local/lib/python3.10/site-packages/docutils/core.py", line 224, in publish
    self.document = self.reader.read(self.source, self.parser,
  File "/usr/local/lib/python3.10/site-packages/sphinx/io.py", line 108, in read
    self.parse()
  File "/usr/local/lib/python3.10/site-packages/docutils/readers/__init__.py", line 76, in parse
    self.parser.parse(self.input, document)
  File "/usr/local/lib/python3.10/site-packages/sphinx/parsers.py", line 80, in parse
    self.statemachine.run(inputlines, document, inliner=self.inliner)
  File "/usr/local/lib/python3.10/site-packages/docutils/parsers/rst/states.py", line 169, in run
    results = StateMachineWS.run(self, input_lines, input_offset,
  File "/usr/local/lib/python3.10/site-packages/docutils/statemachine.py", line 233, in run
    context, next_state, result = self.check_line(
  File "/usr/local/lib/python3.10/site-packages/docutils/statemachine.py", line 445, in check_line
    return method(match, context, next_state)
  File "/usr/local/lib/python3.10/site-packages/docutils/parsers/rst/states.py", line 3024, in text
    self.section(title.lstrip(), source, style, lineno + 1, messages)
  File "/usr/local/lib/python3.10/site-packages/docutils/parsers/rst/states.py", line 325, in section
    self.new_subsection(title, lineno, messages)
  File "/usr/local/lib/python3.10/site-packages/docutils/parsers/rst/states.py", line 391, in new_subsection
    newabsoffset = self.nested_parse(
  File "/usr/local/lib/python3.10/site-packages/docutils/parsers/rst/states.py", line 279, in nested_parse
    state_machine.run(block, input_offset, memo=self.memo,
  File "/usr/local/lib/python3.10/site-packages/docutils/parsers/rst/states.py", line 195, in run
    results = StateMachineWS.run(self, input_lines, input_offset)
  File "/usr/local/lib/python3.10/site-packages/docutils/statemachine.py", line 233, in run
    context, next_state, result = self.check_line(
  File "/usr/local/lib/python3.10/site-packages/docutils/statemachine.py", line 445, in check_line
    return method(match, context, next_state)
  File "/usr/local/lib/python3.10/site-packages/docutils/parsers/rst/states.py", line 2785, in underline
    self.section(title, source, style, lineno - 1, messages)
  File "/usr/local/lib/python3.10/site-packages/docutils/parsers/rst/states.py", line 325, in section
    self.new_subsection(title, lineno, messages)
  File "/usr/local/lib/python3.10/site-packages/docutils/parsers/rst/states.py", line 391, in new_subsection
    newabsoffset = self.nested_parse(
  File "/usr/local/lib/python3.10/site-packages/docutils/parsers/rst/states.py", line 279, in nested_parse
    state_machine.run(block, input_offset, memo=self.memo,
  File "/usr/local/lib/python3.10/site-packages/docutils/parsers/rst/states.py", line 195, in run
    results = StateMachineWS.run(self, input_lines, input_offset)
  File "/usr/local/lib/python3.10/site-packages/docutils/statemachine.py", line 233, in run
    context, next_state, result = self.check_line(
  File "/usr/local/lib/python3.10/site-packages/docutils/statemachine.py", line 445, in check_line
    return method(match, context, next_state)
  File "/usr/local/lib/python3.10/site-packages/docutils/parsers/rst/states.py", line 2355, in explicit_markup
    nodelist, blank_finish = self.explicit_construct(match)
  File "/usr/local/lib/python3.10/site-packages/docutils/parsers/rst/states.py", line 2367, in explicit_construct
    return method(self, expmatch)
  File "/usr/local/lib/python3.10/site-packages/docutils/parsers/rst/states.py", line 2104, in directive
    return self.run_directive(
  File "/usr/local/lib/python3.10/site-packages/docutils/parsers/rst/states.py", line 2154, in run_directive
    result = directive_instance.run()
  File "/usr/local/lib/python3.10/site-packages/IPython/sphinxext/ipython_directive.py", line 1029, in run
    rows, figure = self.shell.process_block(block)
  File "/usr/local/lib/python3.10/site-packages/IPython/sphinxext/ipython_directive.py", line 728, in process_block
    self.process_input(data, input_prompt, lineno)
  File "/usr/local/lib/python3.10/site-packages/IPython/sphinxext/ipython_directive.py", line 600, in process_input
    raise RuntimeError('Non Expected warning in `{}` line {}'.format(filename, lineno))
RuntimeError: Non Expected warning in `/home/pandas/doc/source/user_guide/basics.rst` line 2150

Exception occurred:
  File "/usr/local/lib/python3.10/site-packages/IPython/sphinxext/ipython_directive.py", line 600, in process_input
    raise RuntimeError('Non Expected warning in `{}` line {}'.format(filename, lineno))
RuntimeError: Non Expected warning in `/home/pandas/doc/source/user_guide/basics.rst` line 2150
The full traceback has been saved in /tmp/sphinx-err-03g2yb_t.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!

Also here the log stored by sphinx. However it gives not a lot more information:

root@1cffd0126e92:/home/pandas/doc# cat  /tmp/sphinx-err-03g2yb_t.log
# Platform:         linux; (Linux-5.15.49-linuxkit-aarch64-with-glibc2.31)
# Sphinx version:   6.2.1
# Python version:   3.10.8 (CPython)
# Docutils version: 0.19
# Jinja2 version:   3.1.2
# Pygments version: 2.15.1

# Last messages:
#   reading sources... [ 95%] reference/options
#   reading sources... [ 95%] reference/plotting
#   reading sources... [ 95%] reference/resampling
#   reading sources... [ 95%] reference/series
#   reading sources... [ 95%] reference/style
#   reading sources... [ 95%] reference/testing
#   reading sources... [ 95%] reference/window
#   reading sources... [ 95%] user_guide/10min
#   reading sources... [ 95%] user_guide/advanced
#   reading sources... [ 95%] user_guide/basics

# Loaded extensions:
#   sphinx.ext.mathjax (6.2.1)
#   alabaster (0.7.13)
#   sphinxcontrib.applehelp (1.0.4)
#   sphinxcontrib.devhelp (1.0.2)
#   sphinxcontrib.htmlhelp (2.0.1)
#   sphinxcontrib.serializinghtml (1.1.5)
#   sphinxcontrib.qthelp (1.0.3)
#   contributors (0.1)
#   IPython.sphinxext.ipython_directive (unknown version)
#   IPython.sphinxext.ipython_console_highlighting (unknown version)
#   matplotlib.sphinxext.plot_directive (3.7.1)
#   sphinx.ext.autodoc.preserve_defaults (6.2.1)
#   sphinx.ext.autodoc.type_comment (6.2.1)
#   sphinx.ext.autodoc.typehints (6.2.1)
#   sphinx.ext.autodoc (6.2.1)
#   sphinx.ext.autosummary (6.2.1)
#   numpydoc (1.5.0)
#   sphinx_copybutton (0.5.2)
#   sphinx_design (0.4.1)
#   sphinx_toggleprompt (0.4.0)
#   sphinx.ext.coverage (6.2.1)
#   sphinx.ext.doctest (6.2.1)
#   sphinx.ext.extlinks (6.2.1)
#   sphinx.ext.ifconfig (6.2.1)
#   sphinx.ext.intersphinx (6.2.1)
#   sphinx.ext.linkcode (6.2.1)
#   sphinx.ext.todo (6.2.1)
#   nbsphinx (0.9.1)
#   pydata_sphinx_theme (unknown version)

# Traceback:
Traceback (most recent call last):
  File "/usr/local/lib/python3.10/site-packages/sphinx/cmd/build.py", line 285, in build_main
    app.build(args.force_all, args.filenames)
  File "/usr/local/lib/python3.10/site-packages/sphinx/application.py", line 353, in build
    self.builder.build_update()
  File "/usr/local/lib/python3.10/site-packages/sphinx/builders/__init__.py", line 311, in build_update
    self.build(to_build,
  File "/usr/local/lib/python3.10/site-packages/sphinx/builders/__init__.py", line 328, in build
    updated_docnames = set(self.read())
  File "/usr/local/lib/python3.10/site-packages/sphinx/builders/__init__.py", line 435, in read
    self._read_serial(docnames)
  File "/usr/local/lib/python3.10/site-packages/sphinx/builders/__init__.py", line 456, in _read_serial
    self.read_doc(docname)
  File "/usr/local/lib/python3.10/site-packages/sphinx/builders/__init__.py", line 512, in read_doc
    publisher.publish()
  File "/usr/local/lib/python3.10/site-packages/docutils/core.py", line 224, in publish
    self.document = self.reader.read(self.source, self.parser,
  File "/usr/local/lib/python3.10/site-packages/sphinx/io.py", line 108, in read
    self.parse()
  File "/usr/local/lib/python3.10/site-packages/docutils/readers/__init__.py", line 76, in parse
    self.parser.parse(self.input, document)
  File "/usr/local/lib/python3.10/site-packages/sphinx/parsers.py", line 80, in parse
    self.statemachine.run(inputlines, document, inliner=self.inliner)
  File "/usr/local/lib/python3.10/site-packages/docutils/parsers/rst/states.py", line 169, in run
    results = StateMachineWS.run(self, input_lines, input_offset,
  File "/usr/local/lib/python3.10/site-packages/docutils/statemachine.py", line 233, in run
    context, next_state, result = self.check_line(
  File "/usr/local/lib/python3.10/site-packages/docutils/statemachine.py", line 445, in check_line
    return method(match, context, next_state)
  File "/usr/local/lib/python3.10/site-packages/docutils/parsers/rst/states.py", line 3024, in text
    self.section(title.lstrip(), source, style, lineno + 1, messages)
  File "/usr/local/lib/python3.10/site-packages/docutils/parsers/rst/states.py", line 325, in section
    self.new_subsection(title, lineno, messages)
  File "/usr/local/lib/python3.10/site-packages/docutils/parsers/rst/states.py", line 391, in new_subsection
    newabsoffset = self.nested_parse(
  File "/usr/local/lib/python3.10/site-packages/docutils/parsers/rst/states.py", line 279, in nested_parse
    state_machine.run(block, input_offset, memo=self.memo,
  File "/usr/local/lib/python3.10/site-packages/docutils/parsers/rst/states.py", line 195, in run
    results = StateMachineWS.run(self, input_lines, input_offset)
  File "/usr/local/lib/python3.10/site-packages/docutils/statemachine.py", line 233, in run
    context, next_state, result = self.check_line(
  File "/usr/local/lib/python3.10/site-packages/docutils/statemachine.py", line 445, in check_line
    return method(match, context, next_state)
  File "/usr/local/lib/python3.10/site-packages/docutils/parsers/rst/states.py", line 2785, in underline
    self.section(title, source, style, lineno - 1, messages)
  File "/usr/local/lib/python3.10/site-packages/docutils/parsers/rst/states.py", line 325, in section
    self.new_subsection(title, lineno, messages)
  File "/usr/local/lib/python3.10/site-packages/docutils/parsers/rst/states.py", line 391, in new_subsection
    newabsoffset = self.nested_parse(
  File "/usr/local/lib/python3.10/site-packages/docutils/parsers/rst/states.py", line 279, in nested_parse
    state_machine.run(block, input_offset, memo=self.memo,
  File "/usr/local/lib/python3.10/site-packages/docutils/parsers/rst/states.py", line 195, in run
    results = StateMachineWS.run(self, input_lines, input_offset)
  File "/usr/local/lib/python3.10/site-packages/docutils/statemachine.py", line 233, in run
    context, next_state, result = self.check_line(
  File "/usr/local/lib/python3.10/site-packages/docutils/statemachine.py", line 445, in check_line
    return method(match, context, next_state)
  File "/usr/local/lib/python3.10/site-packages/docutils/parsers/rst/states.py", line 2355, in explicit_markup
    nodelist, blank_finish = self.explicit_construct(match)
  File "/usr/local/lib/python3.10/site-packages/docutils/parsers/rst/states.py", line 2367, in explicit_construct
    return method(self, expmatch)
  File "/usr/local/lib/python3.10/site-packages/docutils/parsers/rst/states.py", line 2104, in directive
    return self.run_directive(
  File "/usr/local/lib/python3.10/site-packages/docutils/parsers/rst/states.py", line 2154, in run_directive
    result = directive_instance.run()
  File "/usr/local/lib/python3.10/site-packages/IPython/sphinxext/ipython_directive.py", line 1029, in run
    rows, figure = self.shell.process_block(block)
  File "/usr/local/lib/python3.10/site-packages/IPython/sphinxext/ipython_directive.py", line 728, in process_block
    self.process_input(data, input_prompt, lineno)
  File "/usr/local/lib/python3.10/site-packages/IPython/sphinxext/ipython_directive.py", line 600, in process_input
    raise RuntimeError('Non Expected warning in `{}` line {}'.format(filename, lineno))
RuntimeError: Non Expected warning in `/home/pandas/doc/source/user_guide/basics.rst` line 2150

On doing some research it looks like this might be related to numpy/numpy#16073
So it looks like the issue is produced due to my processor. (ARM chip Apple M1)

[lithomas1]

Do you want to have a crack at this issue?

The line mentioned

"C": pd.Series(np.array(np.random.randn(8), dtype="uint8"))

doesn't seem right, so it don't think it is an issue with your hardware
(Just guessing, I think it's because a negative number got generated by np.random.randn, which cannot be converted to an unsigned int.)

[DominikBerger01]

take