QST: Error while building document

[Manjugadupudi]

Research

• I have searched the [pandas] tag on StackOverflow for similar questions.

• I have asked my usage related question on StackOverflow.

Link to question on StackOverflow

https://stackoverflow.com/questions/30807270/build-pandas-documentation-from-source-using-installed-pandas-rather-than-an-inp

Question about pandas

I am trying to build documentation in my system as per the instructions, [here](https://pandas.pydata.org/docs/dev/development/contributing_documentation.html#how-to-build-the-pandas-documentation). Here is the error message,

Traceback =========

Traceback (most recent call last):
  File "C:\Users\xxxxx\pandasDev\pandas\pandasvenv\Lib\site-packages\sphinx\cmd\build.py", line 432, in build_main
    app.build(args.force_all, args.filenames)
    ~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "C:\Users\xxxxx\pandasDev\pandas\pandasvenv\Lib\site-packages\sphinx\application.py", line 426, in build
    self.builder.build_update()
    ~~~~~~~~~~~~~~~~~~~~~~~~~^^
  File "C:\Users\xxxxx\pandasDev\pandas\pandasvenv\Lib\site-packages\sphinx\builders\__init__.py", line 375, in build_update
    self.build(
    ~~~~~~~~~~^
        to_build,
        ^^^^^^^^^
    ...<2 lines>...
        method='update',
        ^^^^^^^^^^^^^^^^
    )
    ^
  File "C:\Users\xxxxx\pandasDev\pandas\pandasvenv\Lib\site-packages\sphinx\builders\__init__.py", line 403, in build
    updated_docnames = set(self.read())
                           ~~~~~~~~~^^
  File "C:\Users\xxxxx\pandasDev\pandas\pandasvenv\Lib\site-packages\sphinx\builders\__init__.py", line 519, in read
    self._read_serial(docnames)
    ~~~~~~~~~~~~~~~~~^^^^^^^^^^
  File "C:\Users\xxxxx\pandasDev\pandas\pandasvenv\Lib\site-packages\sphinx\builders\__init__.py", line 584, in _read_serial
    self.read_doc(docname)
    ~~~~~~~~~~~~~^^^^^^^^^
  File "C:\Users\xxxxx\pandasDev\pandas\pandasvenv\Lib\site-packages\sphinx\builders\__init__.py", line 648, in read_doc
    publisher.publish()
    ~~~~~~~~~~~~~~~~~^^
  File "C:\Users\xxxxx\pandasDev\pandas\pandasvenv\Lib\site-packages\docutils\core.py", line 234, in publish
    self.document = self.reader.read(self.source, self.parser,
                    ~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^
                                     self.settings)
                                     ^^^^^^^^^^^^^^
  File "C:\Users\xxxxx\pandasDev\pandas\pandasvenv\Lib\site-packages\sphinx\io.py", line 103, in read
    self.parse()
    ~~~~~~~~~~^^
  File "C:\Users\xxxxx\pandasDev\pandas\pandasvenv\Lib\site-packages\docutils\readers\__init__.py", line 76, in parse
    self.parser.parse(self.input, document)
    ~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^
  File "C:\Users\xxxxx\pandasDev\pandas\pandasvenv\Lib\site-packages\sphinx\parsers.py", line 86, in parse
    self.statemachine.run(inputlines, document, inliner=self.inliner)
    ~~~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "C:\Users\xxxxx\pandasDev\pandas\pandasvenv\Lib\site-packages\docutils\parsers\rst\states.py", line 169, in run
    results = StateMachineWS.run(self, input_lines, input_offset,
                                 input_source=document['source'])
  File "C:\Users\xxxxx\pandasDev\pandas\pandasvenv\Lib\site-packages\docutils\statemachine.py", line 233, in run
    context, next_state, result = self.check_line(
                                  ~~~~~~~~~~~~~~~^
        context, state, transitions)
        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "C:\Users\xxxxx\pandasDev\pandas\pandasvenv\Lib\site-packages\docutils\statemachine.py", line 445, in check_line
    return method(match, context, next_state)
  File "C:\Users\xxxxx\pandasDev\pandas\pandasvenv\Lib\site-packages\docutils\parsers\rst\states.py", line 3034, in text
    self.section(title.lstrip(), source, style, lineno + 1, messages)
    ~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "C:\Users\xxxxx\pandasDev\pandas\pandasvenv\Lib\site-packages\docutils\parsers\rst\states.py", line 325, in section
    self.new_subsection(title, lineno, messages)
    ~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^
  File "C:\Users\xxxxx\pandasDev\pandas\pandasvenv\Lib\site-packages\docutils\parsers\rst\states.py", line 391, in new_subsection
    newabsoffset = self.nested_parse(
          self.state_machine.input_lines[offset:], input_offset=absoffset,
          node=section_node, match_titles=True)
  File "C:\Users\xxxxx\pandasDev\pandas\pandasvenv\Lib\site-packages\docutils\parsers\rst\states.py", line 279, in nested_parse
    state_machine.run(block, input_offset, memo=self.memo,
    ~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
                      node=node, match_titles=match_titles)
                      ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "C:\Users\xxxxx\pandasDev\pandas\pandasvenv\Lib\site-packages\docutils\parsers\rst\states.py", line 195, in run
    results = StateMachineWS.run(self, input_lines, input_offset)
  File "C:\Users\xxxxx\pandasDev\pandas\pandasvenv\Lib\site-packages\docutils\statemachine.py", line 233, in run
    context, next_state, result = self.check_line(
                                  ~~~~~~~~~~~~~~~^
        context, state, transitions)
        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "C:\Users\xxxxx\pandasDev\pandas\pandasvenv\Lib\site-packages\docutils\statemachine.py", line 445, in check_line
    return method(match, context, next_state)
  File "C:\Users\xxxxx\pandasDev\pandas\pandasvenv\Lib\site-packages\docutils\parsers\rst\states.py", line 2790, in underline
    self.section(title, source, style, lineno - 1, messages)
    ~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "C:\Users\xxxxx\pandasDev\pandas\pandasvenv\Lib\site-packages\docutils\parsers\rst\states.py", line 325, in section
    self.new_subsection(title, lineno, messages)
    ~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^
  File "C:\Users\xxxxx\pandasDev\pandas\pandasvenv\Lib\site-packages\docutils\parsers\rst\states.py", line 391, in new_subsection
    newabsoffset = self.nested_parse(
          self.state_machine.input_lines[offset:], input_offset=absoffset,
          node=section_node, match_titles=True)
  File "C:\Users\xxxxx\pandasDev\pandas\pandasvenv\Lib\site-packages\docutils\parsers\rst\states.py", line 279, in nested_parse
    state_machine.run(block, input_offset, memo=self.memo,
    ~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
                      node=node, match_titles=match_titles)
                      ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "C:\Users\xxxxx\pandasDev\pandas\pandasvenv\Lib\site-packages\docutils\parsers\rst\states.py", line 195, in run
    results = StateMachineWS.run(self, input_lines, input_offset)
  File "C:\Users\xxxxx\pandasDev\pandas\pandasvenv\Lib\site-packages\docutils\statemachine.py", line 233, in run
    context, next_state, result = self.check_line(
                                  ~~~~~~~~~~~~~~~^
        context, state, transitions)
        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "C:\Users\xxxxx\pandasDev\pandas\pandasvenv\Lib\site-packages\docutils\statemachine.py", line 445, in check_line
    return method(match, context, next_state)
  File "C:\Users\xxxxx\pandasDev\pandas\pandasvenv\Lib\site-packages\docutils\parsers\rst\states.py", line 2357, in explicit_markup
    nodelist, blank_finish = self.explicit_construct(match)
                             ~~~~~~~~~~~~~~~~~~~~~~~^^^^^^^
  File "C:\Users\xxxxx\pandasDev\pandas\pandasvenv\Lib\site-packages\docutils\parsers\rst\states.py", line 2369, in explicit_construct
    return method(self, expmatch)
  File "C:\Users\xxxxx\pandasDev\pandas\pandasvenv\Lib\site-packages\docutils\parsers\rst\states.py", line 2106, in directive
    return self.run_directive(
           ~~~~~~~~~~~~~~~~~~^
        directive_class, match, type_name, option_presets)
        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "C:\Users\xxxxx\pandasDev\pandas\pandasvenv\Lib\site-packages\docutils\parsers\rst\states.py", line 2156, in run_directive
    result = directive_instance.run()
  File "C:\Users\xxxxx\pandasDev\pandas\pandasvenv\Lib\site-packages\IPython\sphinxext\ipython_directive.py", line 1035, in run
    rows, figure = self.shell.process_block(block)
                   ~~~~~~~~~~~~~~~~~~~~~~~~^^^^^^^
  File "C:\Users\xxxxx\pandasDev\pandas\pandasvenv\Lib\site-packages\IPython\sphinxext\ipython_directive.py", line 733, in process_block
    self.process_input(data, input_prompt, lineno)
    ~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "C:\Users\xxxxx\pandasDev\pandas\pandasvenv\Lib\site-packages\IPython\sphinxext\ipython_directive.py", line 585, in process_input
    raise RuntimeError(
        "Unexpected exception in `{}` line {}".format(filename, lineno)
    )
RuntimeError: Unexpected exception in `C:\Users\xxxxx\pandasDev\pandas\doc\source\user_guide\io.rst` line 5478

Wondering if everyone is same error or it is just for me?

[vkverma9534]

The build fails while executing an IPython directive in doc/source/user_guide/io.rst (~line 5478). Pandas docs run live code during Sphinx builds, and this error likely comes from an environment mismatch (wrong pandas being imported or incompatible doc dependencies), not from an .rst syntax issue. This is probably environment-related--can anyone confirm or share similar experiences?

[rhshadrach]

Can you post the output of pd.show_versions(). To keep the issue tracker from having open issues lacking information, closing for now. Once posted will reopen.

[Manjugadupudi]

INSTALLED VERSIONS

commit : 13fc510
python : 3.13.9
python-bits : 64
OS : Windows
OS-release : 11
Version : 10.0.26100
machine : AMD64
processor : Intel64 Family 6 Model 186 Stepping 3, GenuineIntel
byteorder : little
LC_ALL : None
LANG : None
LOCALE : English_United States.1252

pandas : 3.0.0rc1+23.g13fc5105ca
numpy : 2.3.5
dateutil : 2.9.0.post0
pip : 25.2
Cython : 3.2.3
sphinx : 8.2.3
IPython : 9.8.0
adbc-driver-postgresql: None
adbc-driver-sqlite : None
bs4 : 4.14.3
bottleneck : 1.6.0
fastparquet : 2025.12.0
fsspec : 2025.12.0
html5lib : 1.1
hypothesis : 6.148.8
gcsfs : 2025.12.0
jinja2 : 3.1.6
lxml.etree : 6.0.2
matplotlib : 3.10.8
numba : 0.63.1
numexpr : 2.14.1
odfpy : None
openpyxl : 3.1.5
psycopg2 : 2.9.11
pymysql : 1.4.6
pyarrow : 22.0.0
pyiceberg : 0.10.0
pyreadstat : 1.3.2
pytest : 9.0.2
python-calamine : None
pytz : 2025.2
pyxlsb : 1.0.10
s3fs : 2025.12.0
scipy : 1.16.3
sqlalchemy : 2.0.45
tables : 3.10.2
tabulate : 0.9.0
xarray : 2025.12.0
xlrd : 2.0.2
xlsxwriter : 3.2.9
zstandard : 0.25.0
qtpy : None
pyqt5 : None`

[rhshadrach]

Cannot reproduce on my end. It appears the code that is failing is from the ORC section of the IO user guide. Can you try running that in a script or REPL? If that is successful, try python doc/make.py clean && python doc/make.py html.