"Handler <function mangle_docstrings at 0x7f64b5ba57b8> for event 'autodoc-process-docstring' threw an exception" again

The recent release of numpydoc 1.6.0 caused our builds to start failing with the exact error from #268. Pegging numpydoc to 1.5.0 allows our builds to continue.

Excerpt from pyproject.toml:

[tool.poetry.dependencies]
python = ">=3.8,<4"
pydantic = "^2.3.0"
anyio = ">=3.7.1,<5.0.0"


[tool.poetry.group.doc]
optional = true
[tool.poetry.group.doc.dependencies]
ansys-sphinx-theme = "^0.9.8"
autodoc_pydantic = "^2.0"
httpx = "^0.23.3"
numpydoc = "^1.4.0"
sphinx = "^6.2.1"
sphinx-autobuild = "^2021.3.14"
sphinx-autodoc-typehints = "^1.23.0, !=1.23.4"
sphinx-copybutton = "^0.5.2"
sphinx_design = "^0.4.1"
sphinx_code_tabs = "^0.5.3"
sphinx-gallery = "^0.13.0"
sphinx_mdinclude= "^0.5.3"
sphinx-notfound-page = "^0.8.3"
sphinx-tabs = ">=1.2.1,<3.5.0"
sphinxcontrib-websupport = "^1.2.4"
sphinxemoji = "^0.2.0"
toml = "^0.10.2" # Needed by conf.py
# `sphinx-toolbox` requires `cachecontrol`, which is incompatible with `urllib3>=2`
# See https://github.com/ionrock/cachecontrol/issues/292.
urllib3 = "<2"
tox = "^4.4.6"

Sphinx v6.2.1

Error:

[app] emitting event: 'build-finished'(ExtensionError("Handler <function mangle_docstrings at 0x7f512e29b760> for event 'autodoc-process-d

Traceback (most recent call last):
  File "/home/nsharp/ver/bdm-python-api/.venv/lib/python3.10/site-packages/sphinx/events.py", line 96, in emit
    results.append(listener.handler(self.app, *args))
  File "/home/nsharp/ver/bdm-python-api/.venv/lib/python3.10/site-packages/numpydoc/numpydoc.py", line 214, in mangle_docstrings
    report = validate(doc)
  File "/home/nsharp/ver/bdm-python-api/.venv/lib/python3.10/site-packages/numpydoc/validate.py", line 619, in validate
    ).get(doc.source_file_def_line or 1, [])
  File "/home/nsharp/ver/bdm-python-api/.venv/lib/python3.10/site-packages/numpydoc/validate.py", line 312, in source_file_def_line
    def_line = next(
StopIteration

The above exception was the direct cause of the following exception:

Traceback (most recent call last):
  File "/home/nsharp/ver/bdm-python-api/.venv/lib/python3.10/site-packages/sphinx/cmd/build.py", line 285, in build_main
    app.build(args.force_all, args.filenames)
  File "/home/nsharp/ver/bdm-python-api/.venv/lib/python3.10/site-packages/sphinx/application.py", line 353, in build
    self.builder.build_update()
  File "/home/nsharp/ver/bdm-python-api/.venv/lib/python3.10/site-packages/sphinx/builders/__init__.py", line 311, in build_update
    self.build(to_build,
  File "/home/nsharp/ver/bdm-python-api/.venv/lib/python3.10/site-packages/sphinx/builders/__init__.py", line 328, in build
    updated_docnames = set(self.read())
  File "/home/nsharp/ver/bdm-python-api/.venv/lib/python3.10/site-packages/sphinx/builders/__init__.py", line 435, in read
    self._read_serial(docnames)
  File "/home/nsharp/ver/bdm-python-api/.venv/lib/python3.10/site-packages/sphinx/builders/__init__.py", line 456, in _read_serial
    self.read_doc(docname)
  File "/home/nsharp/ver/bdm-python-api/.venv/lib/python3.10/site-packages/sphinx/builders/__init__.py", line 512, in read_doc
    publisher.publish()
  File "/home/nsharp/ver/bdm-python-api/.venv/lib/python3.10/site-packages/docutils/core.py", line 217, in publish
    self.document = self.reader.read(self.source, self.parser,
  File "/home/nsharp/ver/bdm-python-api/.venv/lib/python3.10/site-packages/sphinx/io.py", line 108, in read
    self.parse()
  File "/home/nsharp/ver/bdm-python-api/.venv/lib/python3.10/site-packages/docutils/readers/__init__.py", line 78, in parse
    self.parser.parse(self.input, document)
  File "/home/nsharp/ver/bdm-python-api/.venv/lib/python3.10/site-packages/sphinx/parsers.py", line 80, in parse
    self.statemachine.run(inputlines, document, inliner=self.inliner)
  File "/home/nsharp/ver/bdm-python-api/.venv/lib/python3.10/site-packages/docutils/parsers/rst/states.py", line 170, in run
    results = StateMachineWS.run(self, input_lines, input_offset,
  File "/home/nsharp/ver/bdm-python-api/.venv/lib/python3.10/site-packages/docutils/statemachine.py", line 240, in run
    context, next_state, result = self.check_line(
  File "/home/nsharp/ver/bdm-python-api/.venv/lib/python3.10/site-packages/docutils/statemachine.py", line 452, in check_line
    return method(match, context, next_state)
  File "/home/nsharp/ver/bdm-python-api/.venv/lib/python3.10/site-packages/docutils/parsers/rst/states.py", line 2779, in underline
    self.section(title, source, style, lineno - 1, messages)
  File "/home/nsharp/ver/bdm-python-api/.venv/lib/python3.10/site-packages/docutils/parsers/rst/states.py", line 327, in section
    self.new_subsection(title, lineno, messages)
  File "/home/nsharp/ver/bdm-python-api/.venv/lib/python3.10/site-packages/docutils/parsers/rst/states.py", line 393, in new_subsection
    newabsoffset = self.nested_parse(
  File "/home/nsharp/ver/bdm-python-api/.venv/lib/python3.10/site-packages/docutils/parsers/rst/states.py", line 281, in nested_parse
    state_machine.run(block, input_offset, memo=self.memo,
  File "/home/nsharp/ver/bdm-python-api/.venv/lib/python3.10/site-packages/docutils/parsers/rst/states.py", line 196, in run
    results = StateMachineWS.run(self, input_lines, input_offset)
  File "/home/nsharp/ver/bdm-python-api/.venv/lib/python3.10/site-packages/docutils/statemachine.py", line 240, in run
    context, next_state, result = self.check_line(
  File "/home/nsharp/ver/bdm-python-api/.venv/lib/python3.10/site-packages/docutils/statemachine.py", line 452, in check_line
    return method(match, context, next_state)
  File "/home/nsharp/ver/bdm-python-api/.venv/lib/python3.10/site-packages/docutils/parsers/rst/states.py", line 2354, in explicit_markup
    self.explicit_list(blank_finish)
  File "/home/nsharp/ver/bdm-python-api/.venv/lib/python3.10/site-packages/docutils/parsers/rst/states.py", line 2379, in explicit_list
    newline_offset, blank_finish = self.nested_list_parse(
  File "/home/nsharp/ver/bdm-python-api/.venv/lib/python3.10/site-packages/docutils/parsers/rst/states.py", line 318, in nested_list_parse
    state_machine.run(block, input_offset, memo=self.memo,
  File "/home/nsharp/ver/bdm-python-api/.venv/lib/python3.10/site-packages/docutils/parsers/rst/states.py", line 196, in run
    results = StateMachineWS.run(self, input_lines, input_offset)
  File "/home/nsharp/ver/bdm-python-api/.venv/lib/python3.10/site-packages/docutils/statemachine.py", line 240, in run
    context, next_state, result = self.check_line(
  File "/home/nsharp/ver/bdm-python-api/.venv/lib/python3.10/site-packages/docutils/statemachine.py", line 452, in check_line
    return method(match, context, next_state)
  File "/home/nsharp/ver/bdm-python-api/.venv/lib/python3.10/site-packages/docutils/parsers/rst/states.py", line 2657, in explicit_markup
    nodelist, blank_finish = self.explicit_construct(match)
  File "/home/nsharp/ver/bdm-python-api/.venv/lib/python3.10/site-packages/docutils/parsers/rst/states.py", line 2364, in explicit_construct
    return method(self, expmatch)
  File "/home/nsharp/ver/bdm-python-api/.venv/lib/python3.10/site-packages/docutils/parsers/rst/states.py", line 2101, in directive
    return self.run_directive(
  File "/home/nsharp/ver/bdm-python-api/.venv/lib/python3.10/site-packages/docutils/parsers/rst/states.py", line 2151, in run_directive
    result = directive_instance.run()
  File "/home/nsharp/ver/bdm-python-api/.venv/lib/python3.10/site-packages/sphinx/ext/autodoc/directive.py", line 146, in run
    result = parse_generated_content(self.state, params.result, documenter)
  File "/home/nsharp/ver/bdm-python-api/.venv/lib/python3.10/site-packages/sphinx/ext/autodoc/directive.py", line 89, in parse_generated_content
    nested_parse_with_titles(state, content, node)
  File "/home/nsharp/ver/bdm-python-api/.venv/lib/python3.10/site-packages/sphinx/util/nodes.py", line 328, in nested_parse_with_titles
    return state.nested_parse(content, content_offset, node, match_titles=1)
  File "/home/nsharp/ver/bdm-python-api/.venv/lib/python3.10/site-packages/docutils/parsers/rst/states.py", line 281, in nested_parse
    state_machine.run(block, input_offset, memo=self.memo,
  File "/home/nsharp/ver/bdm-python-api/.venv/lib/python3.10/site-packages/docutils/parsers/rst/states.py", line 196, in run
    results = StateMachineWS.run(self, input_lines, input_offset)
  File "/home/nsharp/ver/bdm-python-api/.venv/lib/python3.10/site-packages/docutils/statemachine.py", line 240, in run
    context, next_state, result = self.check_line(
  File "/home/nsharp/ver/bdm-python-api/.venv/lib/python3.10/site-packages/docutils/statemachine.py", line 452, in check_line
    return method(match, context, next_state)
  File "/home/nsharp/ver/bdm-python-api/.venv/lib/python3.10/site-packages/docutils/parsers/rst/states.py", line 2352, in explicit_markup
    nodelist, blank_finish = self.explicit_construct(match)
  File "/home/nsharp/ver/bdm-python-api/.venv/lib/python3.10/site-packages/docutils/parsers/rst/states.py", line 2364, in explicit_construct
    return method(self, expmatch)
  File "/home/nsharp/ver/bdm-python-api/.venv/lib/python3.10/site-packages/docutils/parsers/rst/states.py", line 2101, in directive
    return self.run_directive(
  File "/home/nsharp/ver/bdm-python-api/.venv/lib/python3.10/site-packages/docutils/parsers/rst/states.py", line 2151, in run_directive
    result = directive_instance.run()
  File "/home/nsharp/ver/bdm-python-api/.venv/lib/python3.10/site-packages/sphinx/domains/__init__.py", line 286, in run
    return super().run()
  File "/home/nsharp/ver/bdm-python-api/.venv/lib/python3.10/site-packages/sphinx/directives/__init__.py", line 266, in run
    nested_parse_with_titles(self.state, self.content, contentnode, self.content_offset)
  File "/home/nsharp/ver/bdm-python-api/.venv/lib/python3.10/site-packages/sphinx/util/nodes.py", line 328, in nested_parse_with_titles
    return state.nested_parse(content, content_offset, node, match_titles=1)
  File "/home/nsharp/ver/bdm-python-api/.venv/lib/python3.10/site-packages/docutils/parsers/rst/states.py", line 281, in nested_parse
    state_machine.run(block, input_offset, memo=self.memo,
  File "/home/nsharp/ver/bdm-python-api/.venv/lib/python3.10/site-packages/docutils/parsers/rst/states.py", line 196, in run
    results = StateMachineWS.run(self, input_lines, input_offset)
  File "/home/nsharp/ver/bdm-python-api/.venv/lib/python3.10/site-packages/docutils/statemachine.py", line 240, in run
    context, next_state, result = self.check_line(
  File "/home/nsharp/ver/bdm-python-api/.venv/lib/python3.10/site-packages/docutils/statemachine.py", line 452, in check_line
    return method(match, context, next_state)
  File "/home/nsharp/ver/bdm-python-api/.venv/lib/python3.10/site-packages/docutils/parsers/rst/states.py", line 2354, in explicit_markup
    self.explicit_list(blank_finish)
  File "/home/nsharp/ver/bdm-python-api/.venv/lib/python3.10/site-packages/docutils/parsers/rst/states.py", line 2379, in explicit_list
    newline_offset, blank_finish = self.nested_list_parse(
  File "/home/nsharp/ver/bdm-python-api/.venv/lib/python3.10/site-packages/docutils/parsers/rst/states.py", line 318, in nested_list_parse
    state_machine.run(block, input_offset, memo=self.memo,
  File "/home/nsharp/ver/bdm-python-api/.venv/lib/python3.10/site-packages/docutils/parsers/rst/states.py", line 196, in run
    results = StateMachineWS.run(self, input_lines, input_offset)
  File "/home/nsharp/ver/bdm-python-api/.venv/lib/python3.10/site-packages/docutils/statemachine.py", line 240, in run
    context, next_state, result = self.check_line(
  File "/home/nsharp/ver/bdm-python-api/.venv/lib/python3.10/site-packages/docutils/statemachine.py", line 452, in check_line
    return method(match, context, next_state)
  File "/home/nsharp/ver/bdm-python-api/.venv/lib/python3.10/site-packages/docutils/parsers/rst/states.py", line 2657, in explicit_markup
    nodelist, blank_finish = self.explicit_construct(match)
  File "/home/nsharp/ver/bdm-python-api/.venv/lib/python3.10/site-packages/docutils/parsers/rst/states.py", line 2364, in explicit_construct
    return method(self, expmatch)
  File "/home/nsharp/ver/bdm-python-api/.venv/lib/python3.10/site-packages/docutils/parsers/rst/states.py", line 2101, in directive
    return self.run_directive(
  File "/home/nsharp/ver/bdm-python-api/.venv/lib/python3.10/site-packages/docutils/parsers/rst/states.py", line 2151, in run_directive
    result = directive_instance.run()
  File "/home/nsharp/ver/bdm-python-api/.venv/lib/python3.10/site-packages/sphinx/ext/autosummary/__init__.py", line 230, in run
    items = self.get_items(names)
  File "/home/nsharp/ver/bdm-python-api/.venv/lib/python3.10/site-packages/sphinx/ext/autosummary/__init__.py", line 375, in get_items
    documenter.add_content(None)
  File "/home/nsharp/ver/bdm-python-api/.venv/lib/python3.10/site-packages/sphinx/ext/autodoc/__init__.py", line 619, in add_content
    for i, line in enumerate(self.process_doc(docstrings)):
  File "/home/nsharp/ver/bdm-python-api/.venv/lib/python3.10/site-packages/sphinx/ext/autodoc/__init__.py", line 564, in process_doc
    self.env.app.emit('autodoc-process-docstring',
  File "/home/nsharp/ver/bdm-python-api/.venv/lib/python3.10/site-packages/sphinx/application.py", line 464, in emit
    return self.events.emit(event, *args, allowed_exceptions=allowed_exceptions)
  File "/home/nsharp/ver/bdm-python-api/.venv/lib/python3.10/site-packages/sphinx/events.py", line 107, in emit
    raise ExtensionError(__("Handler %r for event %r threw an exception") %
sphinx.errors.ExtensionError: Handler <function mangle_docstrings at 0x7f512e29b760> for event 'autodoc-process-docstring' threw an exception (exception: )

Extension error (numpydoc.numpydoc):
Handler <function mangle_docstrings at 0x7f512e29b760> for event 'autodoc-process-docstring' threw an exception (exception: )
make: *** [Makefile:19: linkcheck] Error 2
make: Leaving directory '/home/nsharp/ver/bdm-python-api/doc'

Start with the documentation dependencies in pyproject.toml, then inspect numpydoc/numpydoc.py and numpydoc/validate.py at the traceback locations. Reproduce the Sphinx 6.2.1 build with numpydoc 1.6.0 and compare it with 1.5.0; the issue is resolved when the documented build completes without this exception.